/ Hex Artifact Content
Login

Artifact 53a8235ebece1090111da51f18833bdf3fbd869c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5510: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5530: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5540: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5550: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5570: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5590: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
55d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
55e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55f0: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5600: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5610: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5640: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5650: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5680: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5690: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
56b0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
56c0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
56d0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
56e0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
56f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5700: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5710: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5720: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5730: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5740: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5750: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5760: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5770: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5780: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5790: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
57a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
57b0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
57e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
57f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5800: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5820: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5830: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5840: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5850: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5870: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5880: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5890: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
58a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
58d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
58e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5910: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5920: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5940: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5950: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5960: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
59a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
59b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
59c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59d0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
59e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
59f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5a00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5a40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5a80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5aa0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5ab0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5ac0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5af0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5b30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5b70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5bb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5bf0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5c00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5c10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5c40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5c50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5c60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5c90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5ca0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5ce0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5cf0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d20: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5d30: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5d50: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5d70: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5d80: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5d90: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5da0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5db0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5dc0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5dd0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5de0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5df0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5e00: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5e10: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5e20: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
5e30: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5e40: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5e50: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5e60: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5e70: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5e80: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5e90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5ea0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5eb0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5ec0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ed0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5ee0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5ef0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5f00: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5f10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5f20: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5f30: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5f40: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5f50: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5f60: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5f70: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5f80: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5f90: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5fa0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5fb0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5fc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5fd0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5fe0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ff0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6000: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6010: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6020: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6030: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6040: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6050: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6060: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6070: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6080: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6090: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
60a0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
60b0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
60c0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
60d0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
60e0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
60f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6100: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6110: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6120: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6130: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6140: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6150: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6160: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6170: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6180: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6190: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
61a0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
61b0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
61c0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
61d0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
61e0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
61f0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6200: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6210: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  anged..*/.#defin
6220: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6230: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
6240: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6270: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6280: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6290: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
62a0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
62b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
62c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
62d0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
62e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
62f0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
6300: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6310: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
6320: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6340: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6350: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6360: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6370: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6380: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6390: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
63a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
63b0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
63c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
63d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
63e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
63f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6400: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
6410: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6420: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
6430: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6450: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6460: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6470: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6480: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6490: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
64a0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
64b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
64c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
64d0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
64e0: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1000../*.** CAPI
64f0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6500: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6510: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6520: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6530: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6540: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6550: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6560: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6570: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6580: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6590: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
65a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
65b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65c0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
65d0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
65e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
65f0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6600: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6610: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6630: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6640: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6650: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6660: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6670: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6680: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6690: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
66a0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
66b0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
66c0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
66d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
66e0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
66f0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6700: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6710: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6720: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6730: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6740: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6750: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6760: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6770: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6780: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6790: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
67a0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
67b0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
67c0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
67d0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
67e0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
67f0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
6800: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
6810: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
6820: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
6830: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
6840: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
6850: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
6860: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
6870: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
6880: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
6890: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
68a0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
68b0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
68c0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
68d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
68e0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
68f0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
6900: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
6910: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
6920: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
6930: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
6940: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
6950: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
6960: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
6970: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
6980: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
6990: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
69a0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
69b0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
69c0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
69d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
69e0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
69f0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6a00: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
6a10: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
6a20: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
6a30: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
6a40: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
6a50: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
6a60: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
6a70: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
6a80: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
6a90: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
6aa0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
6ab0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
6ac0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
6ad0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
6ae0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
6af0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6b00: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
6b10: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
6b20: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
6b30: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
6b40: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
6b50: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
6b60: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
6b70: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
6b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6b90: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
6ba0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
6bb0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6bc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6be0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
6bf0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
6c00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6c10: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
6c20: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
6c30: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6c40: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
6c50: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
6c60: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
6c70: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
6c80: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
6c90: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6ca0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
6cb0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
6cc0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
6cd0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
6ce0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6cf0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6d00: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6d10: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6d20: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6d30: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6d40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6d50: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6d60: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6d70: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6d80: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6d90: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6da0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6db0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
6dc0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
6dd0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6de0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6df0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6e00: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6e10: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6e20: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6e30: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6e40: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6e50: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6e60: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6e70: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
6e80: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
6e90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6ea0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
6eb0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
6ec0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6ed0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
6ee0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
6ef0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
6f00: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
6f10: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
6f20: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
6f30: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
6f40: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
6f50: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
6f60: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
6f70: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
6f80: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
6f90: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
6fa0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
6fb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6fc0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
6fd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6fe0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
6ff0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
7000: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7010: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7020: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7030: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7040: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7050: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7060: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7070: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7080: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7090: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
70a0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
70b0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
70c0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
70d0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
70e0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
70f0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
7100: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7110: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7120: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7130: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7140: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7160: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7170: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7180: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7190: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
71a0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
71b0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
71c0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
71d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
71e0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
71f0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7200: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7210: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7220: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7230: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7240: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7250: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7260: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7270: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7280: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7290: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
72a0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
72b0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
72c0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
72d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
72e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
72f0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7300: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7310: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7320: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7330: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7340: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7350: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7360: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7370: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7380: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7390: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
73a0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
73b0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
73c0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
73d0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
73e0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
73f0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7400: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7410: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7420: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7430: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7440: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7450: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7460: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7470: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7480: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7490: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
74a0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
74b0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
74c0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
74d0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
74e0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
74f0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7500: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7510: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7520: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7530: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7540: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7550: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7560: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7570: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7580: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7590: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
75a0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
75b0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
75c0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
75d0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
75e0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
75f0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7600: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7610: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7620: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7630: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7640: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7650: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7660: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7670: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7680: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7690: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
76a0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
76b0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
76c0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
76d0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
76e0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
76f0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7700: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7710: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7720: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7730: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7740: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7750: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7760: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
7780: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
7790: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
77a0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
77b0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
77c0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
77d0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
77e0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
77f0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
7800: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
7810: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
7820: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
7830: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7840: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7850: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7860: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
7870: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
7880: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
7890: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
78a0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
78b0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
78c0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
78d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
78e0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
78f0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7900: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
7910: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
7920: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
7930: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7940: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
7950: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
7960: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
7970: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7980: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
7990: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
79a0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
79b0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
79c0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
79d0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
79e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
79f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
7a00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7a10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
7a20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
7a40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
7a60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7a80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7aa0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7ab0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
7ac0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7ad0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
7ae0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
7b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7b20: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
7b30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
7b40: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
7b50: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
7b60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7b80: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
7b90: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
7ba0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7bc0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
7bd0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
7be0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
7bf0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
7c00: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
7c10: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
7c20: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
7c30: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
7c40: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
7c50: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7c60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7c70: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
7c80: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
7c90: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
7ca0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
7cb0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
7cc0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
7cd0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7ce0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7cf0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7d00: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7d10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7d20: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7d30: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7d40: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7d50: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7d60: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7d70: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
7d80: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
7d90: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
7da0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
7db0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
7dc0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
7dd0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
7de0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
7df0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
7e00: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
7e10: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
7e20: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
7e30: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
7e40: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
7e50: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
7e60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7e70: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
7e80: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
7e90: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
7ea0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
7eb0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7ec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
7ed0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
7ee0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7ef0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
7f00: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
7f10: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
7f20: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7f30: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
7f40: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
7f50: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7f60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7f70: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
7f80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7f90: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
7fa0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
7fb0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
7fc0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
7fd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7fe0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
7ff0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8000: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8010: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8020: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8030: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8040: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8050: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8060: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8070: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8080: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8090: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
80a0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
80b0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
80c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
80d0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
80e0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
80f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8100: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8110: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8120: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8130: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8140: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8150: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8160: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8190: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
81a0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
81b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
81c0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
81d0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
81e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
81f0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8200: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8210: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8220: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8230: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8240: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8250: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8260: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8270: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8280: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8290: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
82a0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
82b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
82c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
82d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
82e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
82f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8300: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8310: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
8320: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8330: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8340: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8350: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8360: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8370: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8380: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8390: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
83a0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
83b0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
83c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
83d0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
83e0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
83f0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8400: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8410: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8420: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8430: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8440: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8450: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8460: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8470: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8480: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8490: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
84a0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
84b0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
84c0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
84d0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
84e0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
84f0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8500: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8510: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8520: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8530: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8540: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8550: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8560: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8570: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8590: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
85a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
85b0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
85c0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
85d0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
85e0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
85f0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8600: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8610: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8620: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8630: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8640: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8650: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8660: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8670: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8680: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8690: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
86a0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
86b0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
86c0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
86d0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
86e0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
86f0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8700: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8710: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8720: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8730: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8740: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8750: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8760: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8770: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8780: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8790: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
87a0: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
87b0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
87c0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
87d0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
87e0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
87f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8800: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8810: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8820: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
8830: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8850: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8860: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8870: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8880: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8890: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
88a0: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
88b0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
88c0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
88d0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
88e0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
88f0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
8900: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8910: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8920: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8930: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8950: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8960: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8970: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8980: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
8990: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
89a0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
89b0: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
89c0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
89d0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
89e0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
89f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8a00: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
8a10: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
8a20: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
8a30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8a40: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
8a50: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
8a60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8a70: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8a80: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8a90: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8aa0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8ab0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8ac0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8ad0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8ae0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8af0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b00: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8b10: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8b20: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8b30: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8b40: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8b50: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8b60: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8b70: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8b80: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8b90: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8ba0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8bb0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8bc0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8bd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8be0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8bf0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8c00: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8c10: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8c20: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8c30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8c40: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8c50: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8c60: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8c70: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8c80: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
8c90: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
8ca0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
8cb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8cc0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
8cd0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
8ce0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
8cf0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
8d00: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
8d10: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
8d20: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
8d30: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
8d40: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
8d50: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
8d60: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
8d70: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
8d80: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8d90: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
8da0: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
8db0: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
8dc0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
8dd0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
8de0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
8df0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
8e00: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
8e10: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
8e20: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
8e30: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
8e40: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
8e50: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
8e60: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
8e70: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
8e80: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
8e90: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
8ea0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
8eb0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
8ec0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
8ed0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
8ee0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
8ef0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
8f00: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
8f10: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
8f20: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
8f30: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
8f40: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
8f50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
8f60: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
8f70: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
8f80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
8f90: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
8fa0: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
8fb0: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
8fc0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
8fd0: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
8fe0: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
8ff0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9000: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9010: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9020: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
9030: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9040: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9050: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9060: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9070: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9080: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9090: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
90a0: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
90b0: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
90c0: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
90d0: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
90e0: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
90f0: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9100: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9110: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9120: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9130: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9140: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9150: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
9160: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
9170: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
9180: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9190: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
91a0: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
91b0: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
91c0: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
91d0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
91e0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
91f0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
9200: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
9210: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
9220: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
9230: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
9240: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
9250: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
9260: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
9270: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
9280: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9290: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
92a0: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
92b0: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
92c0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
92d0: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
92e0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
92f0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
9300: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
9310: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9320: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
9330: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9340: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
9350: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
9360: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
9370: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
9380: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9390: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
93a0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
93b0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
93c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
93d0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
93e0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
93f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
9400: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
9410: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
9420: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
9430: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9440: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9450: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9460: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9470: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9480: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9490: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
94a0: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
94b0: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
94c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
94d0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
94e0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
94f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9500: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9510: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9520: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9530: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9540: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9550: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9560: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9570: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9580: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
95a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
95b0: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
95c0: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
95d0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
95e0: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
95f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9600: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9610: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9620: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9630: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9640: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9650: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9660: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9670: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9680: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9690: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
96a0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
96b0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
96c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
96d0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
96e0: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
96f0: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
9700: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9710: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9720: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9730: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9740: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9750: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9760: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9770: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9780: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9790: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
97a0: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
97b0: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
97c0: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
97d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
97e0: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
97f0: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
9800: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
9810: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
9820: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
9830: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9850: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9860: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9870: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9880: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9890: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
98a0: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
98b0: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
98c0: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
98d0: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
98e0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
98f0: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
9900: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
9910: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
9920: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
9930: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9940: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9950: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9960: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9970: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9980: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
9990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
99a0: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
99b0: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
99c0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
99d0: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
99e0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
99f0: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
9a00: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
9a10: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
9a20: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
9a30: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
9a40: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
9a50: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
9a60: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
9a70: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
9a80: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
9a90: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
9aa0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9ab0: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
9ac0: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
9ad0: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
9ae0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
9af0: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
9b00: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9b10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9b20: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
9b30: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
9b40: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
9b50: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
9b60: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
9b70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
9b80: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
9b90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9ba0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
9bb0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
9bc0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
9bd0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
9be0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
9bf0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
9c00: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
9c10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9c20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
9c30: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
9c40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
9c50: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
9c60: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
9c70: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
9c80: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
9c90: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
9ca0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
9cb0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
9cc0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
9cd0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
9ce0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
9cf0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
9d00: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
9d10: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
9d20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
9d30: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
9d40: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
9d50: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
9d60: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
9d70: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
9d80: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
9d90: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
9da0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
9db0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
9dc0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
9dd0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
9de0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
9df0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
9e00: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
9e10: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
9e20: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
9e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9e40: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
9e50: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
9e60: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
9e70: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
9e80: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
9e90: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
9ea0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
9eb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
9ec0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
9ed0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
9ee0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
9ef0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
9f00: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
9f10: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
9f20: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
9f30: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
9f40: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
9f50: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
9f60: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9f70: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
9f80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
9f90: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
9fa0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
9fb0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
9fc0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
9fd0: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
9fe0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
9ff0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a000: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a010: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a020: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a030: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a040: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a050: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a070: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a080: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a090: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a0a0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a0b0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a0c0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a0d0: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a0e0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a0f0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c  tements..** </ul
a100: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
a120: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
a130: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
a140: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
a150: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
a160: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
a170: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
a180: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
a190: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
a1a0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
a1b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
a1c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a1d0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
a1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
a1f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a200: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
a210: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
a220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a230: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
a240: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
a250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a260: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
a270: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
a280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a290: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
a2a0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
a2b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a2c0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
a2d0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
a2e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a2f0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
a300: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
a310: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
a320: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
a330: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
a340: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
a350: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a360: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
a370: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a380: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
a390: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
a3a0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
a3b0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
a3c0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
a3d0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
a3e0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
a3f0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
a400: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
a410: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
a420: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
a430: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
a440: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
a450: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
a460: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
a470: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
a480: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
a490: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
a4a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
a4b0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
a4c0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
a4d0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
a4e0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
a4f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a500: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
a510: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
a520: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
a530: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
a540: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
a550: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
a560: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
a570: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
a580: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
a590: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
a5a0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
a5b0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
a5c0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
a5d0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
a5e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
a5f0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
a600: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
a610: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
a620: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
a630: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
a640: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
a650: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
a660: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
a670: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
a680: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
a690: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
a6a0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
a6b0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
a6c0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
a6d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
a6e0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
a6f0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
a700: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
a710: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
a720: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
a730: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
a740: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
a750: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a760: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
a770: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
a780: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
a790: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
a7a0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
a7b0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
a7c0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
a7d0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
a7e0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
a7f0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
a800: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
a810: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
a820: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
a830: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
a840: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
a850: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
a860: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
a870: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
a880: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
a890: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
a8a0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
a8b0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
a8c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
a8d0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
a8e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
a8f0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
a900: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
a910: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
a920: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
a930: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
a940: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
a950: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
a960: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
a970: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
a980: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
a990: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
a9a0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
a9b0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
a9c0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
a9d0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
a9e0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
a9f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
aa00: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
aa10: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
aa20: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
aa30: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
aa40: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
aa50: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
aa60: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
aa70: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
aa80: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
aa90: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
aaa0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
aab0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
aac0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
aad0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
aae0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
aaf0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
ab00: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
ab10: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
ab20: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
ab30: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
ab40: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
ab50: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
ab60: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
ab70: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
ab80: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
ab90: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
aba0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
abb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
abc0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
abd0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
abe0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
abf0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
ac00: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
ac10: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
ac20: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
ac30: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
ac40: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
ac50: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
ac60: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
ac70: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
ac80: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
ac90: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
aca0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
acb0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
acc0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
acd0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
ace0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
acf0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
ad00: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
ad10: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
ad20: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
ad30: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
ad40: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
ad50: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
ad60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
ad70: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
ad80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ad90: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
ada0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
adb0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
adc0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
add0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
ade0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
adf0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
ae00: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
ae10: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
ae20: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
ae30: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
ae40: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
ae50: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
ae60: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
ae70: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
ae80: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
ae90: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
aea0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
aeb0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
aec0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
aed0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
aee0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
aef0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
af00: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
af10: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
af20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
af30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
af40: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
af50: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
af60: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
af70: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
af80: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
af90: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
afa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
afb0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
afc0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
afd0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
afe0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
aff0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b000: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b010: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b020: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b030: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
b040: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
b050: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
b060: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
b070: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b080: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b090: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
b0a0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
b0b0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
b0c0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
b0d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b0e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b0f0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
b100: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
b110: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
b120: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b130: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
b140: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b150: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
b160: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b170: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
b180: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b190: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
b1a0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
b1b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
b1c0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
b1d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b1e0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
b1f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
b200: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
b210: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
b220: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
b230: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
b240: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
b250: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
b260: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
b270: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
b280: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
b290: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
b2a0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
b2b0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
b2c0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
b2d0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
b2e0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
b2f0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
b300: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
b310: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
b320: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
b330: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
b340: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
b350: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
b360: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
b370: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
b380: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
b390: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
b3a0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
b3b0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
b3c0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
b3d0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
b3e0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
b3f0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
b400: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
b410: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
b420: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
b430: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
b440: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
b450: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
b460: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
b470: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
b480: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b490: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
b4a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
b4b0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b4c0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
b4d0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
b4e0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
b4f0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
b500: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
b510: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
b520: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
b530: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
b540: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
b550: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
b560: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
b570: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
b580: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
b590: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
b5a0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
b5b0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
b5c0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
b5d0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
b5e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
b5f0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
b600: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
b610: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
b620: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
b630: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
b640: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
b650: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
b660: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
b670: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
b680: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
b690: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
b6a0: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
b6b0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
b6c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
b6d0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
b6e0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
b6f0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
b700: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
b710: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
b720: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
b730: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
b740: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
b750: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
b760: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
b770: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
b780: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
b790: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
b7a0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
b7b0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
b7c0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
b7d0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
b7e0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
b7f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
b800: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
b810: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
b820: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
b830: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
b840: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
b850: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
b860: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
b870: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
b880: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b890: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
b8a0: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
b8b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b8c0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
b8d0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
b8e0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
b8f0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
b900: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
b910: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
b920: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
b930: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
b940: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
b950: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
b960: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
b970: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
b980: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
b990: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
b9a0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
b9b0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
b9c0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
b9d0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
b9e0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
b9f0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
ba00: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
ba10: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
ba20: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
ba30: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
ba40: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
ba50: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
ba60: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
ba70: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
ba80: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
ba90: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
baa0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
bab0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
bac0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
bad0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
bae0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
baf0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
bb00: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
bb10: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
bb20: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
bb30: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
bb40: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
bb50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
bb60: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
bb70: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
bb80: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
bb90: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
bba0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
bbb0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
bbc0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
bbd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
bbe0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
bbf0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
bc00: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
bc10: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
bc20: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
bc30: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
bc40: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
bc50: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
bc60: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
bc70: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
bc80: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
bc90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
bca0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
bcb0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
bcc0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
bcd0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
bce0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
bcf0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
bd00: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
bd10: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
bd20: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
bd30: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
bd40: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
bd50: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
bd60: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
bd70: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
bd80: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
bd90: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
bda0: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
bdb0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
bdc0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
bdd0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
bde0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
bdf0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
be00: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
be10: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
be20: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
be30: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
be40: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
be50: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
be60: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
be70: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
be80: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
be90: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
bea0: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
beb0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
bec0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
bed0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
bee0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
bef0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
bf00: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
bf10: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
bf20: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
bf30: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
bf40: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
bf50: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
bf60: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
bf70: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
bf80: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
bf90: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
bfa0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
bfb0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
bfc0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
bfd0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
bfe0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
bff0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c000: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c010: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c020: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c030: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c040: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
c050: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
c060: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
c070: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c080: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
c090: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
c0a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
c0b0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
c0c0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
c0d0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
c0e0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
c0f0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
c100: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
c110: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
c120: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
c130: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
c140: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
c150: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
c160: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
c170: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
c180: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
c190: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
c1a0: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
c1b0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
c1c0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
c1d0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
c1e0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
c1f0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
c200: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
c210: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
c220: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
c230: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
c240: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
c250: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
c260: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
c270: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
c280: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
c290: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
c2a0: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
c2b0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
c2c0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
c2d0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
c2e0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
c2f0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
c300: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
c310: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
c320: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
c330: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
c340: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
c350: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
c360: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
c370: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
c380: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
c390: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
c3a0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
c3b0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
c3c0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c3d0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
c3e0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
c3f0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
c400: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
c410: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
c420: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
c430: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
c440: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
c450: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
c460: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
c470: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
c480: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
c490: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
c4a0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
c4b0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
c4c0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
c4d0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
c4e0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
c4f0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
c500: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
c510: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
c520: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
c530: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
c540: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
c550: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
c560: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
c570: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
c580: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
c590: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
c5a0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
c5b0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
c5c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c5d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c5e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
c5f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
c600: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
c610: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
c620: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
c630: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c640: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c650: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
c660: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
c670: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c680: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c690: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
c6a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
c6b0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
c6c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c6d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c6e0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
c6f0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
c700: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
c710: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
c720: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
c730: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
c740: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c750: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c760: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
c770: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
c780: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
c790: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
c7a0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
c7b0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
c7c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
c7d0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
c7e0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
c7f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
c800: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
c810: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
c820: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c830: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
c840: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
c850: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
c860: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
c870: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
c880: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
c890: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
c8a0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
c8b0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
c8c0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
c8d0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
c8e0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
c8f0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
c900: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
c910: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
c920: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
c930: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
c940: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
c950: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
c960: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
c970: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
c980: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
c990: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
c9a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
c9b0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
c9c0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
c9d0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
c9e0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
c9f0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
ca00: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ca10: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ca20: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ca30: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ca40: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ca50: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
ca60: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ca70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ca80: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
ca90: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
caa0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cab0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cac0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
cad0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
cae0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
caf0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
cb00: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
cb10: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
cb20: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
cb30: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
cb40: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
cb50: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
cb60: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
cb70: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
cb80: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
cb90: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
cba0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
cbb0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
cbc0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
cbd0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cbe0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
cbf0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
cc00: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
cc10: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
cc20: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
cc30: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
cc40: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
cc50: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
cc60: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
cc70: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
cc80: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
cc90: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
cca0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
ccb0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ccc0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
ccd0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
cce0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
ccf0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
cd00: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
cd10: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
cd20: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cd30: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
cd40: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
cd50: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
cd60: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
cd70: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
cd80: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
cd90: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
cda0: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
cdb0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
cdc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
cdd0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
cde0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
cdf0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ce00: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ce10: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
ce20: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
ce30: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
ce40: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
ce50: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ce60: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ce70: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
ce80: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ce90: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cea0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
ceb0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
cec0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
ced0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
cee0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
cef0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
cf00: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
cf10: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
cf20: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
cf30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
cf40: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
cf50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
cf60: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
cf70: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
cf80: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
cf90: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
cfa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
cfb0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
cfc0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
cfd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cfe0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
cff0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d000: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d010: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d020: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d030: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
d040: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
d050: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
d060: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
d070: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
d080: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
d090: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
d0a0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
d0b0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
d0c0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
d0d0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
d0e0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
d0f0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
d100: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
d110: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d120: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d130: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
d140: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d150: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
d160: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
d170: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
d180: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
d190: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
d1a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
d1b0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
d1c0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
d1d0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
d1e0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
d1f0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
d200: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
d210: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
d220: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
d230: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
d240: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
d250: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
d260: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
d270: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
d280: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
d290: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
d2a0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
d2b0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
d2c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d2d0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
d2e0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
d2f0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
d300: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d310: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d320: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
d330: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
d340: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
d350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
d360: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
d370: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
d380: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
d390: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d3a0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
d3b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
d3c0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
d3d0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
d3e0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
d3f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
d400: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
d410: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
d420: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
d430: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
d440: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
d450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
d460: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
d470: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
d480: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
d490: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
d4a0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
d4b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d4c0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
d4d0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
d4e0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
d4f0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
d500: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
d510: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
d520: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
d530: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
d540: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
d550: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
d560: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
d570: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
d580: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
d590: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
d5a0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
d5b0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
d5c0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
d5d0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
d5e0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
d5f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
d600: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
d610: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
d620: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
d630: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d640: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
d650: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d660: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
d670: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
d680: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
d690: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
d6a0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
d6b0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
d6c0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
d6d0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d6e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d6f0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
d700: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
d710: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d720: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
d730: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
d740: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
d750: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
d760: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
d770: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
d780: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
d790: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
d7a0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
d7b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d7c0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
d7d0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
d7e0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
d7f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d800: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
d810: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
d820: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
d830: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
d840: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
d850: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d860: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
d870: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
d880: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
d890: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
d8a0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
d8b0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d8c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d8d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d8e0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
d8f0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
d900: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d910: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
d920: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d930: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
d940: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
d950: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
d960: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
d970: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
d980: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
d990: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
d9a0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
d9b0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
d9c0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
d9d0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
d9e0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
d9f0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
da00: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
da10: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
da20: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
da30: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
da40: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
da50: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
da60: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
da70: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
da80: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
da90: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
daa0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
dab0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
dac0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
dad0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
dae0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
daf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
db00: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
db10: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
db20: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
db30: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
db40: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
db50: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
db60: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
db70: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
db80: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
db90: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
dba0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
dbb0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dbc0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
dbd0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
dbe0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
dbf0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
dc00: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
dc10: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
dc20: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
dc30: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
dc40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dc50: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
dc60: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
dc70: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
dc80: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
dc90: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
dca0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dcb0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
dcc0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
dcd0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
dce0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
dcf0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
dd00: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
dd10: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
dd20: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
dd30: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
dd40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
dd50: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
dd60: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
dd70: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
dd80: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
dd90: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
dda0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
ddb0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
ddc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
ddd0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
dde0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
ddf0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
de00: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
de10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
de20: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
de30: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
de40: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
de50: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
de60: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
de70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
de80: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
de90: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
dea0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
deb0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
dec0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
ded0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
dee0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
def0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
df00: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
df10: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
df20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
df30: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
df40: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
df50: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
df60: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
df70: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
df80: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
df90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
dfa0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
dfb0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
dfc0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
dfd0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
dfe0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
dff0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e000: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e010: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e020: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e030: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
e040: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
e050: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
e060: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
e070: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
e080: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
e090: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
e0a0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
e0b0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
e0c0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
e0d0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
e0e0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
e0f0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
e100: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
e110: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
e120: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
e130: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e140: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
e150: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
e160: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
e170: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
e180: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
e190: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
e1a0: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
e1b0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
e1c0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
e1d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e1e0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
e1f0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
e200: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e210: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
e220: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
e230: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
e240: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e250: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
e260: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
e270: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
e280: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
e290: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
e2a0: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
e2b0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
e2c0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
e2d0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
e2e0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
e2f0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
e300: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
e310: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
e320: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
e330: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
e340: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
e350: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
e360: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
e370: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
e380: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
e390: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
e3a0: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
e3b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e3c0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
e3d0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
e3e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
e3f0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
e400: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
e410: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
e420: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
e430: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
e440: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
e450: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
e460: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
e470: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
e480: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
e490: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
e4a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e4b0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
e4c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
e4d0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
e4e0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
e4f0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
e500: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
e510: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e520: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
e530: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
e540: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
e550: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
e560: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
e570: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
e580: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e590: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
e5a0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
e5b0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
e5c0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
e5d0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
e5e0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
e5f0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
e600: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
e610: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
e620: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
e630: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
e640: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
e650: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
e660: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
e670: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
e680: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
e690: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
e6a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
e6b0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
e6c0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
e6d0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
e6e0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
e6f0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
e700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
e710: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
e720: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
e730: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e740: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
e750: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
e760: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
e770: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
e780: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
e790: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
e7a0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
e7b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e7c0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
e7d0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
e7e0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
e7f0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
e800: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
e810: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
e820: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
e830: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
e840: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e850: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
e860: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
e870: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
e880: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
e890: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
e8a0: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
e8b0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
e8c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
e8d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
e8e0: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
e8f0: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
e900: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
e910: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
e920: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
e930: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
e940: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
e950: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
e960: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
e970: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
e980: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
e990: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
e9a0: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
e9b0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
e9c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e9d0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
e9e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
e9f0: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
ea00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ea10: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ea20: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ea30: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ea40: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
ea50: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
ea60: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
ea70: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
ea80: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
ea90: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
eaa0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
eab0: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
eac0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
ead0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
eae0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
eaf0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
eb00: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
eb10: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
eb20: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
eb30: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
eb40: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
eb50: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
eb60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
eb70: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
eb80: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
eb90: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
eba0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
ebb0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
ebc0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
ebd0: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
ebe0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
ebf0: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
ec00: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
ec10: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
ec20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ec30: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
ec40: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
ec50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
ec60: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
ec70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
ec80: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
ec90: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
eca0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
ecb0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
ecc0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ecd0: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
ece0: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
ecf0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
ed00: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
ed10: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
ed20: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
ed30: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
ed40: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
ed50: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
ed60: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
ed70: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
ed80: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
ed90: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
eda0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
edb0: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
edc0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
edd0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
ede0: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
edf0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
ee00: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
ee10: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
ee20: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
ee30: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
ee40: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
ee50: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ee60: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
ee70: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
ee80: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
ee90: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
eea0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
eeb0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
eec0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
eed0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
eee0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
eef0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
ef00: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
ef10: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
ef20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ef30: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
ef40: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
ef50: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
ef60: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
ef70: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
ef80: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
ef90: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
efa0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
efb0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
efc0: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
efd0: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
efe0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
eff0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
f000: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
f010: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
f020: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
f030: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
f040: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
f050: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
f060: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
f070: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
f080: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
f090: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
f0a0: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
f0b0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
f0c0: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
f0d0: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
f0e0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
f0f0: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
f100: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
f110: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
f120: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
f130: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
f140: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
f150: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
f160: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
f170: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
f180: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
f190: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
f1a0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
f1b0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
f1c0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
f1d0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
f1e0: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
f1f0: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
f200: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
f210: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
f220: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
f230: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
f240: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
f250: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
f260: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
f270: 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
f280: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
f290: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
f2a0: 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
f2b0: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
f2c0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
f2d0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
f2e0: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
f2f0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
f300: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
f310: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
f320: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
f330: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
f340: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
f350: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
f360: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
f370: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
f380: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
f390: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
f3a0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
f3b0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
f3c0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
f3d0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
f3e0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
f3f0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
f400: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
f410: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
f420: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
f430: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
f440: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
f450: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
f460: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
f470: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
f480: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
f490: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
f4a0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
f4b0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
f4c0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
f4d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
f4e0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
f4f0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
f500: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
f510: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
f520: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
f530: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
f540: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
f550: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
f560: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
f570: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
f580: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
f590: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
f5a0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
f5b0: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
f5c0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
f5d0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
f5e0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
f5f0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
f600: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
f610: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
f620: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
f630: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
f640: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
f650: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
f660: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
f670: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
f680: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
f690: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
f6a0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
f6b0: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
f6c0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
f6d0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
f6e0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
f6f0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
f700: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
f710: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
f720: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
f730: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
f740: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
f750: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
f760: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
f770: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
f780: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
f790: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
f7a0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
f7b0: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
f7c0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
f7d0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
f7e0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
f7f0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
f800: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
f810: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
f820: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
f830: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
f840: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
f850: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
f860: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
f870: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
f880: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
f890: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
f8a0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
f8b0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
f8c0: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
f8d0: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
f8e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f8f0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
f900: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
f910: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
f920: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
f930: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
f940: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
f950: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
f960: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
f970: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
f980: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
f990: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
f9a0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
f9b0: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
f9c0: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
f9d0: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
f9e0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
f9f0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
fa00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
fa10: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
fa20: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
fa30: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
fa40: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
fa50: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
fa60: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
fa70: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
fa80: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
fa90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
faa0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
fab0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
fac0: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
fad0: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
fae0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
faf0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
fb00: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
fb10: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
fb20: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
fb30: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
fb40: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
fb50: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
fb60: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
fb70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
fb80: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
fb90: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
fba0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
fbb0: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
fbc0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
fbd0: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
fbe0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
fbf0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
fc00: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
fc10: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
fc20: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
fc30: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
fc40: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
fc50: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
fc60: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
fc70: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
fc80: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
fc90: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
fca0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
fcb0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
fcc0: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
fcd0: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
fce0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
fcf0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
fd00: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
fd10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
fd20: 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
fd30: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
fd40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
fd50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
fd60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
fd70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fd80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
fd90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
fda0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
fdb0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
fdc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
fdd0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
fde0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fdf0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
fe00: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
fe10: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
fe20: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
fe30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fe40: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
fe50: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
fe60: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
fe70: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
fe80: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
fe90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
fea0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
feb0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
fec0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
fed0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
fee0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
fef0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
ff00: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
ff10: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
ff20: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
ff30: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ff40: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
ff50: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
ff60: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
ff70: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
ff80: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
ff90: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
ffa0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
ffb0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
ffc0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
ffd0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
ffe0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
fff0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
10000 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
10010 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
10020 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
10030 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
10040 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
10050 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
10060 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
10070 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
10080 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
10090 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
100a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
100b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
100c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
100d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
100e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
100f0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10100 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
10110 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
10120 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
10130 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
10140 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
10150 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
10160 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
10170 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
10180 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10190 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
101a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
101b0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
101c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
101d0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
101e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
101f0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
10200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10210 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
10220 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10230 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10240 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10250 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10260 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10270 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
10280 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
10290 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
102a0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
102b0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
102c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
102d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
102e0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
102f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10300 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
10310 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
10320 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
10330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10340 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10350 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
10360 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
10370 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
10380 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
10390 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
103a0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
103b0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
103c0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
103d0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
103e0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
103f0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
10400 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10410 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
10420 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
10430 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10440 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10450 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10460 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10470 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10480 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10490 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
104a0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
104b0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
104c0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
104d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
104e0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
104f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10500 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
10510 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
10520 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
10530 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10540 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
10550 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10560 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
10570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10580 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
10590 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
105a0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
105b0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
105c0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
105d0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
105e0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
105f0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
10600 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
10610 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
10620 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
10630 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
10640 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
10650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10660 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
10670 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
10680 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
10690 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
106a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
106b0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
106c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
106d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
106e0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
106f0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
10700 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
10710 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
10720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10730 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
10740 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
10750 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
10760 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
10770 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
10780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10790 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
107a0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
107b0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
107c0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
107d0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
107e0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
107f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10800 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10810 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10820 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10830 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10840 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
10850 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
10860 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
10870 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
10880 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
10890 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
108a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
108b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
108c0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
108d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
108e0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
108f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
10900 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10910 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10920 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10930 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
10940 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
10950 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
10960 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
10970 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
10980 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
10990 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
109a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
109b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
109c0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
109d0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
109e0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
109f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10a00 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
10a10 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
10a20 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
10a30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10a40 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
10a50 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
10a60 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
10a70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
10a80 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
10a90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
10aa0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10ab0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
10ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10ad0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
10ae0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10b00 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
10b10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10b20 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
10b30 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
10b40 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
10b50 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
10b60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
10b70 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
10b80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
10b90 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10ba0 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
10bb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
10bc0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
10bd0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
10be0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
10bf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10c00 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
10c10 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
10c20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
10c30 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
10c40 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
10c50 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
10c60 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
10c70 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
10c80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10c90 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
10ca0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
10cb0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
10cc0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
10cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ce0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
10cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10d00 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
10d10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10d20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
10d30 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
10d40 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
10d50 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
10d60 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
10d70 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
10d80 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
10d90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
10da0 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
10db0 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
10dc0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
10dd0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
10de0 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
10df0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
10e00 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
10e10 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
10e20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
10e30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10e40 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
10e50 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
10e60 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
10e70 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
10e80 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
10e90 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
10ea0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
10eb0 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
10ec0 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
10ed0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
10ee0 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
10ef0 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
10f00 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
10f10 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
10f20 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
10f30 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
10f40 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
10f50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
10f60 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
10f70 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
10f80 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
10f90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10fa0 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
10fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
10fc0 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
10fd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
10fe0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
10ff0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
11000 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
11010 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
11020 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
11030 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
11040 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
11050 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
11060 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
11070 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
11080 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
11090 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
110a0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
110b0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
110c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
110d0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
110e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
110f0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11100 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
11110 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
11120 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
11130 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
11140 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11150 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
11160 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
11170 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
11180 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
11190 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
111a0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
111b0 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
111c0 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
111d0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
111e0 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
111f0 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
11200 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
11210 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
11220 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
11230 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
11240 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
11250 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
11260 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
11270 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
11280 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
11290 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
112a0 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
112b0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
112c0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
112d0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
112e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
112f0 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
11300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11310 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
11320 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
11330 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
11340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11350 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11360 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11370 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
11380 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11390 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
113a0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
113b0 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
113c0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
113d0 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
113e0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
113f0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
11400 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
11410 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
11420 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
11430 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
11440 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
11450 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
11460 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
11470 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
11480 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
11490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
114a0 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
114b0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
114c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
114d0 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
114e0 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
114f0 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
11500 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
11510 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
11520 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
11530 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
11540 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
11550 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
11560 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
11570 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
11580 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
11590 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
115a0 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
115b0 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
115c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
115d0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
115e0 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
115f0 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
11600 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
11610 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
11620 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
11630 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
11640 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
11650 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
11660 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
11670 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
11680 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
11690 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
116a0 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
116b0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
116c0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
116d0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
116e0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
116f0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
11700 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11710 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
11720 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
11730 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
11740 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
11750 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
11760 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
11770 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
11780 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
11790 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
117a0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
117b0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
117c0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
117d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
117e0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
117f0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
11800 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
11810 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11820 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
11830 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11840 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
11850 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
11860 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
11870 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
11880 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
11890 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
118a0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
118b0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
118c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
118d0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
118e0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
118f0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11900 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
11910 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
11920 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
11930 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
11940 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
11950 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
11960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11970 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
11980 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11990 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
119a0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
119b0 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
119c0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
119d0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
119e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
119f0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
11a00 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
11a10 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
11a20 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
11a30 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
11a40 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
11a50 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
11a60 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
11a70 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
11a80 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
11a90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11aa0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
11ab0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
11ac0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
11ad0 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
11ae0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
11af0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
11b00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
11b10 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
11b20 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
11b30 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
11b40 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
11b50 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
11b60 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
11b70 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
11b80 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
11b90 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
11ba0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
11bb0 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
11bc0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
11bd0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
11be0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
11bf0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
11c00 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
11c10 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
11c20 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
11c30 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
11c40 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
11c50 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
11c60 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
11c70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
11c80 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
11c90 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
11ca0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
11cb0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
11cc0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
11cd0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
11ce0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
11d00 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
11d10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
11d20 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11d30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11d40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11d50 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11d60 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11d70 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11d80 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11d90 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
11da0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
11db0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
11dc0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
11dd0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
11de0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
11df0 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
11e00 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
11e10 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
11e20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
11e30 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
11e40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
11e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
11e60 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
11e70 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
11e80 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11e90 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
11ea0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11eb0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11ec0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11ed0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11ee0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11ef0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11f00 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
11f10 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
11f20 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
11f30 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
11f40 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
11f50 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
11f60 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
11f70 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
11f80 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
11f90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
11fa0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
11fb0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
11fc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11fd0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
11fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ff0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
12000 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12010 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12020 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12030 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12040 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12050 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12060 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12070 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
12080 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
12090 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
120a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
120b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
120c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
120d0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
120e0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
120f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
12100 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
12110 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
12120 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
12130 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
12140 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
12150 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
12160 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
12170 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
12180 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
12190 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
121a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
121b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
121c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
121d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
121e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
121f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
12200 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
12210 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
12220 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
12230 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
12240 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
12250 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12260 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12270 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12290 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
122a0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
122b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
122c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
122d0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
122e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
122f0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
12300 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12310 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
12320 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
12330 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
12340 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12350 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
12360 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
12370 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
12380 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12390 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
123a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
123b0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
123c0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
123d0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
123e0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
123f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
12400 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
12410 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
12420 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
12430 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12440 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
12450 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
12460 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
12470 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12480 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
12490 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
124a0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
124b0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
124c0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
124d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
124e0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
124f0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
12500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12510 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
12520 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12530 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
12540 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12550 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12560 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12570 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12580 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
12590 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
125a0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
125b0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
125c0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
125d0 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
125e0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
125f0 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
12600 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12610 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
12620 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
12630 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
12640 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
12650 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12660 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
12670 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
12680 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12690 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
126a0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
126b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
126c0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
126d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
126e0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
126f0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
12700 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
12710 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
12720 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
12730 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12740 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
12750 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
12760 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12770 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
12780 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
12790 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
127a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
127b0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
127c0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
127d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
127e0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
127f0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
12800 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
12810 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
12820 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
12830 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
12840 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
12850 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
12860 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
12870 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
12880 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
12890 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
128a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
128b0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
128c0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
128d0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
128e0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
128f0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
12900 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
12910 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
12920 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
12930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
12940 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
12950 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
12960 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
12970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
12980 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
12990 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
129a0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
129b0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
129c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
129d0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
129e0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
129f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
12a00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12a10 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
12a20 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
12a30 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
12a40 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
12a50 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
12a60 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
12a70 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
12a80 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
12a90 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
12aa0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
12ab0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
12ac0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
12ad0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
12ae0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
12af0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
12b00 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
12b10 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
12b20 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
12b30 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
12b40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12b50 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
12b60 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
12b70 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
12b80 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
12b90 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
12ba0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12bb0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
12bc0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
12bd0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
12be0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12bf0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
12c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
12c10 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  I.** <dd> This o
12c20 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12c30 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
12c40 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
12c50 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
12c60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
12c70 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
12c80 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
12c90 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
12ca0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
12cb0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
12cc0 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61  abled. If URI ha
12cd0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
12ce0 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ly enabled, all 
12cf0 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73  filenames.** pas
12d00 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
12d10 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
12d20 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
12d30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
12d40 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
12d50 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
12d60 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
12d70 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
12d80 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
12d90 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
12da0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
12db0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
12dc0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
12dd0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
12de0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
12df0 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f  ed. If it is glo
12e00 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
12e10 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
12e20 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
12e30 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
12e40 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
12e50 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
12e60 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
12e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
12e80 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75  opened. By defau
12e90 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
12ea0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
12eb0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
12ec0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
12ed0 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
12ee0 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
12ef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
12f00 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
12f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ned..**.** [[SQL
12f20 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12f30 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
12f40 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
12f50 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
12f60 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
12f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12f80 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
12f90 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
12fa0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
12fb0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
12fc0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
12fd0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
12fe0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
12ff0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
13000 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
13010 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ps..** </dl>.*/.
13020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13030 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13040 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
13050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13060 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
13070 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
13080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13090 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
130a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
130b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
130c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
130d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
13100 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13110 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
13120 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13130 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
13140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13150 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
13160 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
13170 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
13180 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13190 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
131a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
131b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
131c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
131d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
131e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
131f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
13200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13210 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13220 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
13230 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
13240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13250 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
13260 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
13270 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13290 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
132a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
132b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
132c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
132d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
132e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
132f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
13300 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
13310 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13320 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
13330 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
13340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13350 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
13360 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
13370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13380 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
13390 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
133a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
133b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
133c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
133d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
133e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
133f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
13400 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
13410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13420 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
13430 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
13440 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
13450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13460 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
13470 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
13480 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
13490 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
134a0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
134b0 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
134c0 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
134d0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
134e0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
134f0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
13500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13510 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
13520 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
13530 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13540 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
13550 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
13560 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
13570 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
13580 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
13590 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
135a0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
135b0 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
135c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
135d0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
135e0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
135f0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
13600 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
13610 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
13620 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
13630 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
13640 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
13650 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
13660 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
13670 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
13680 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
13690 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
136a0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
136b0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
136c0 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
136d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
136e0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
136f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
13700 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
13710 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
13720 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13730 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
13740 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
13750 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
13760 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
13770 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
13780 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
13790 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
137a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
137b0 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
137c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
137d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
137e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
137f0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
13800 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
13810 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
13820 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
13830 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
13840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13850 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
13860 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13870 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
13880 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
13890 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
138a0 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
138b0 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
138c0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
138d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
138e0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
138f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
13900 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13910 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13920 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
13930 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
13940 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
13950 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
13960 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
13970 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
13980 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13990 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
139a0 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
139b0 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
139c0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
139d0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
139e0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
139f0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
13a00 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
13a10 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
13a20 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
13a30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13a40 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
13a50 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
13a60 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
13a70 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
13a80 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
13a90 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
13aa0 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
13ab0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
13ac0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
13ad0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
13ae0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
13af0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
13b00 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
13b10 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
13b20 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
13b30 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
13b40 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
13b50 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
13b60 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
13b70 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
13b80 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
13b90 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
13ba0 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
13bb0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
13bc0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
13bd0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
13be0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
13bf0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
13c00 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
13c10 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
13c20 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
13c30 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
13c40 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
13c50 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
13c60 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
13c70 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13c80 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
13c90 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13ca0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13cb0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
13cc0 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
13cd0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13ce0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
13cf0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
13d00 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
13d10 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
13d20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13d30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
13d40 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
13d50 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
13d60 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
13d70 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
13d80 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
13d90 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
13da0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
13db0 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
13dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
13df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
13e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
13e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
13e20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
13e30 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
13e40 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
13e50 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
13e60 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
13e70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
13e80 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
13e90 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
13ea0 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
13eb0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
13ec0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
13ed0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
13ee0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
13ef0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
13f00 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
13f10 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
13f20 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
13f30 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
13f40 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
13f50 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
13f60 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
13f70 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
13f80 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
13f90 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
13fa0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
13fb0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
13fc0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
13fd0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
13fe0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
13ff0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
14000 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
14010 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
14020 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
14030 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
14040 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
14050 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
14060 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
14070 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
14080 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
14090 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
140a0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
140b0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
140c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
140d0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
140e0 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
140f0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
14100 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
14110 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
14120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
14130 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14140 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
14150 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
14160 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14170 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
14180 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
14190 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
141a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
141b0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
141c0 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
141d0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
141e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
141f0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
14200 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
14210 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
14220 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
14230 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
14240 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
14250 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
14260 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
14270 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
14280 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
14290 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
142a0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
142b0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
142c0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
142d0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
142e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
142f0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
14300 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
14310 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
14320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
14330 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
14340 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
14350 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
14360 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
14370 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
14380 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
14390 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
143a0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
143b0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
143c0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
143d0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
143e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
143f0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
14400 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
14410 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
14420 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
14430 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
14440 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
14450 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
14460 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
14470 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
14480 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
14490 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
144a0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
144b0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
144c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
144d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
144e0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
144f0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
14500 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14510 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
14520 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
14550 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41  st argument.  ^A
14560 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
14570 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20  ion 3.7.7, this 
14580 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f  routines.** reco
14590 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  rds the last ins
145a0 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74  ert rowid of bot
145b0 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  h ordinary table
145c0 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74  s and [virtual t
145d0 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e  ables]..** ^If n
145e0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
145f0 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
14600 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
14610 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
14620 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
14630 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
14640 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
14650 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
14660 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
14670 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
14680 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
14690 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
146a0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
146b0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
146c0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
146d0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
146e0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
146f0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
14700 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
14710 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
14720 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
14730 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
14740 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
14750 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
14760 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
14770 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
14780 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
14790 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
147a0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
147b0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
147c0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
147d0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
147e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
147f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
14800 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
14810 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
14820 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
14830 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
14840 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
14850 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
14860 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
14870 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
14880 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
14890 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
148a0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
148b0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
148c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
148d0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
148e0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
148f0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
14900 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
14910 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
14920 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
14930 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
14940 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
14950 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
14960 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
14970 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
14980 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
14990 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
149a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
149b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
149c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
149d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
149e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
149f0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
14a00 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
14a10 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
14a20 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
14a30 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
14a40 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
14a50 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
14a60 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
14a70 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
14a80 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
14a90 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
14aa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
14ab0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
14ac0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
14ad0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
14ae0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
14af0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
14b00 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
14b10 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
14b20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14b30 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
14b40 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
14b50 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
14b60 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
14b70 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
14b80 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
14b90 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
14ba0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
14bb0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
14bc0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14bd0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
14be0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
14bf0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
14c00 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
14c10 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
14c20 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
14c30 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
14c40 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
14c50 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
14c60 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
14c70 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
14c80 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
14c90 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
14ca0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
14cb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
14cc0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
14cd0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
14ce0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
14cf0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
14d00 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
14d10 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
14d20 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
14d30 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
14d40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
14d50 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
14d60 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
14d70 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
14d80 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
14d90 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
14da0 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
14db0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
14dc0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
14dd0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
14de0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
14df0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
14e00 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
14e10 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
14e20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
14e30 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
14e40 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
14e50 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
14e60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
14e70 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
14e80 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
14e90 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
14ea0 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
14eb0 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
14ec0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
14ed0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
14ee0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
14ef0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
14f00 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
14f10 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
14f20 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
14f30 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
14f40 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
14f50 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
14f60 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
14f70 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
14f80 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
14f90 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
14fa0 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
14fb0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
14fc0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
14fd0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
14fe0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
14ff0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
15000 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
15010 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
15020 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
15030 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
15040 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
15050 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
15060 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
15070 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
15080 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
15090 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
150a0 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
150b0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
150c0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
150d0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
150e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
150f0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
15100 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
15110 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
15120 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
15130 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
15140 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
15150 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
15160 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
15170 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
15180 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
15190 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
151a0 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
151b0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
151c0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
151d0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
151e0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
151f0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
15200 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
15210 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
15220 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
15230 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
15240 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
15250 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
15260 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
15270 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
15280 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
15290 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
152a0 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
152b0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
152c0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
152d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
152e0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
152f0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
15300 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
15310 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
15320 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
15330 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
15340 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
15350 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
15360 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
15370 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
15380 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
15390 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
153a0 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
153b0 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
153c0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
153d0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
153e0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
153f0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
15400 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
15410 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
15420 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
15430 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
15440 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
15450 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
15460 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
15470 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
15480 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
15490 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
154a0 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
154b0 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
154c0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
154d0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
154e0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
154f0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
15500 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
15510 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
15520 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
15530 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
15540 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
15550 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
15560 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
15570 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
15580 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
15590 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
155a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
155b0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
155c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
155d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
155e0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
155f0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
15600 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
15610 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15620 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
15630 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
15640 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
15650 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
15660 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15670 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
15680 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
15690 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
156a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
156b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
156c0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
156d0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
156e0 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
156f0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
15700 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
15710 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15720 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
15730 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
15740 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
15750 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15760 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
15770 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
15780 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
15790 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
157a0 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
157b0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
157c0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
157d0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
157e0 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
157f0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
15800 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
15810 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
15820 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
15830 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
15840 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
15850 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
15860 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
15870 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
15880 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
15890 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
158a0 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
158b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
158c0 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
158d0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
158e0 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
158f0 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
15900 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
15910 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
15920 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
15930 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
15940 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
15950 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
15960 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
15970 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
15980 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
15990 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
159a0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
159b0 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
159c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
159d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
159e0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
159f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
15a00 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
15a10 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
15a20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
15a30 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
15a40 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
15a50 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
15a60 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
15a70 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
15a80 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
15a90 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
15aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15ab0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
15ac0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
15ad0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
15ae0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
15af0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
15b00 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
15b10 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
15b20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
15b30 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
15b40 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
15b50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
15b60 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
15b70 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
15b80 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
15b90 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
15ba0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
15bb0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
15bc0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
15bd0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
15be0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
15bf0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
15c00 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
15c10 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
15c20 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
15c30 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
15c40 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
15c50 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
15c60 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
15c70 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
15c80 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
15c90 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
15ca0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
15cb0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
15cc0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
15cd0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
15ce0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
15cf0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
15d00 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
15d10 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
15d20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
15d30 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
15d40 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
15d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
15d60 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
15d70 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
15d80 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
15d90 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
15da0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
15db0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
15dc0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
15dd0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
15de0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
15df0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
15e00 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
15e10 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
15e20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
15e30 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
15e40 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
15e50 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
15e60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
15e70 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
15e80 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
15e90 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
15ea0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
15eb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
15ec0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
15ed0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
15ee0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15ef0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
15f00 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
15f10 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
15f20 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
15f30 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
15f40 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
15f50 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
15f60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
15f70 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15f80 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
15f90 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
15fa0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
15fb0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
15fc0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
15fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
15fe0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
15ff0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
16000 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
16010 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
16020 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16030 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
16040 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
16050 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
16060 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
16070 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
16080 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
16090 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
160a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
160b0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
160c0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
160d0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
160e0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
160f0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
16100 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
16110 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
16120 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
16130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
16140 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
16150 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
16160 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
16170 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
16180 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
16190 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
161a0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
161b0 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
161c0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
161d0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
161e0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
161f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16200 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
16210 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
16220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16230 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
16240 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
16250 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
16260 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
16270 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
16280 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
16290 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
162a0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
162b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
162c0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
162d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
162e0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
162f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
16300 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
16310 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
16320 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
16330 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
16340 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
16350 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
16360 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
16370 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
16380 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
16390 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
163a0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
163b0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
163c0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
163d0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
163e0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
163f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
16400 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
16410 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
16420 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
16430 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
16440 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
16450 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
16460 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
16470 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
16480 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
16490 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
164a0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
164b0 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
164c0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
164d0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
164e0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
164f0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
16500 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
16510 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
16520 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
16530 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
16540 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
16550 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
16560 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
16570 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
16580 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
16590 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
165a0 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
165b0 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
165c0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
165d0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
165e0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
165f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
16600 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
16610 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
16620 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
16630 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
16640 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
16650 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
16660 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
16670 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
16680 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
16690 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
166a0 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
166b0 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
166c0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
166d0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
166e0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
166f0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
16700 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
16710 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
16720 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
16730 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
16740 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
16750 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
16760 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
16770 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
16780 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
16790 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
167a0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
167b0 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
167c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
167d0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
167e0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
167f0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
16800 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
16810 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
16820 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
16830 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
16840 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
16850 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
16860 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
16870 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
16880 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
16890 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
168a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
168b0 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
168c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
168d0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
168e0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
168f0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
16900 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
16910 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
16920 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
16930 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
16940 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
16950 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
16960 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
16970 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
16980 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
16990 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
169a0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
169b0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
169c0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
169d0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
169e0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
169f0 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
16a00 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
16a10 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
16a20 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
16a30 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
16a40 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
16a50 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
16a60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
16a70 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16a80 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
16a90 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
16aa0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
16ab0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
16ac0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
16ad0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
16ae0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
16af0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
16b00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
16b10 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
16b20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
16b30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
16b40 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
16b50 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
16b60 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
16b70 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
16b80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
16b90 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
16ba0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
16bb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16bc0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
16bd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
16be0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
16bf0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
16c00 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
16c10 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
16c20 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
16c30 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
16c40 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
16c50 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
16c60 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
16c70 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
16c80 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
16c90 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
16ca0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
16cb0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16cc0 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
16cd0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
16ce0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
16cf0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
16d00 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
16d10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
16d20 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
16d30 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
16d40 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
16d50 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
16d60 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
16d70 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
16d80 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
16d90 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
16da0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
16db0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
16dc0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
16dd0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
16de0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
16df0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
16e00 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
16e10 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
16e20 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
16e30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
16e40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16e50 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
16e60 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
16e70 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
16e80 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
16e90 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
16ea0 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
16eb0 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
16ec0 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
16ed0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
16ee0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
16ef0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
16f00 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
16f10 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
16f20 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
16f30 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
16f40 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
16f50 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
16f60 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
16f70 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
16f80 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
16f90 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
16fa0 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
16fb0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
16fc0 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
16fd0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
16fe0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
16ff0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
17000 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
17010 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17020 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
17030 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
17040 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
17050 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
17060 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
17070 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
17080 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
17090 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
170a0 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
170b0 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
170c0 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
170d0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
170e0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
170f0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
17100 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
17110 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
17120 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
17130 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
17140 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
17150 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
17160 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
17170 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
17180 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
17190 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
171a0 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
171b0 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
171c0 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
171d0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
171e0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
171f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
17200 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
17210 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17220 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
17230 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
17240 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
17250 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
17260 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
17270 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
17280 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
17290 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
172a0 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
172b0 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
172c0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
172d0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
172e0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
172f0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
17300 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
17310 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
17320 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
17330 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
17340 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
17350 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
17360 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
17370 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
17380 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
17390 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
173a0 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
173b0 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
173c0 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
173d0 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
173e0 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
173f0 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
17400 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
17410 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
17420 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
17430 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
17440 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
17450 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
17460 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
17470 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
17480 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
17490 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
174a0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
174b0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
174c0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
174d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
174e0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
174f0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
17500 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
17510 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
17520 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
17530 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
17540 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
17550 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
17560 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
17570 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
17580 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
17590 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
175a0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
175b0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
175c0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
175d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
175e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
175f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
17600 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
17610 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
17620 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
17630 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
17640 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
17650 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
17660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17670 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
17680 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
17690 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
176a0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
176b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
176c0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
176d0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
176e0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
176f0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
17700 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
17710 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
17720 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
17730 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
17740 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
17750 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
17760 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
17770 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
17780 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
17790 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
177a0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
177b0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
177c0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
177d0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
177e0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
177f0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
17800 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
17810 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
17820 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
17830 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
17840 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
17850 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
17860 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
17870 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
17880 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
17890 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
178a0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
178b0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
178c0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
178d0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
178e0 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
178f0 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
17900 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
17910 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
17920 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
17930 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
17940 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
17950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17960 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
17970 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
17980 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
17990 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
179a0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
179b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
179c0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
179d0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
179e0 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
179f0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
17a00 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20  eared.)^.*/.int 
17a10 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
17a20 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
17a30 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
17a40 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
17a50 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
17a60 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
17a70 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
17a80 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
17a90 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
17aa0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
17ab0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
17ac0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
17ad0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
17ae0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
17af0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
17b00 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
17b10 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
17b20 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
17b30 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
17b40 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
17b50 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
17b60 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
17b70 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
17b80 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
17b90 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
17ba0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
17bb0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
17bc0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
17bd0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
17be0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
17bf0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
17c00 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
17c10 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
17c20 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
17c30 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
17c40 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
17c50 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
17c60 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
17c70 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
17c80 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
17c90 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
17ca0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17cb0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
17cc0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
17cd0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
17ce0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
17cf0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
17d00 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
17d10 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
17d20 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
17d30 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
17d40 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
17d50 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
17d60 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
17d70 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
17d80 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
17d90 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
17da0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
17db0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
17dc0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
17dd0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
17de0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
17df0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
17e00 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
17e10 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
17e20 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
17e30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
17e40 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
17e50 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
17e60 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
17e70 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
17e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17e90 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
17ea0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
17eb0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
17ec0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
17ed0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
17ee0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
17ef0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
17f00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
17f10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
17f20 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
17f30 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
17f40 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
17f50 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
17f60 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
17f70 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
17f80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
17f90 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
17fa0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
17fb0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
17fc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17fd0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
17fe0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
17ff0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
18000 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
18010 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
18020 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
18030 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
18040 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
18050 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
18060 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
18070 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
18080 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
18090 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
180a0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
180b0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
180c0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
180d0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
180e0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
180f0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
18100 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18110 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
18120 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18130 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
18140 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18150 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
18160 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
18170 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
18180 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
18190 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
181a0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
181b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
181c0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
181d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
181e0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
181f0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18200 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
18210 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18220 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
18230 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
18240 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
18250 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
18260 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
18270 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
18280 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
18290 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
182a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
182b0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
182c0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
182d0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
182e0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
182f0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
18300 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
18310 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
18320 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
18330 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
18340 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18350 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
18360 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
18370 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
18380 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
18390 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
183a0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
183b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
183c0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
183d0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
183e0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
183f0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
18400 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
18410 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
18420 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
18430 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
18440 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
18450 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
18460 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
18470 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
18480 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
18490 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
184a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
184b0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
184c0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
184d0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
184e0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
184f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
18500 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
18510 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
18520 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
18530 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
18540 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
18550 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18560 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
18570 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
18580 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
18590 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
185a0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
185b0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
185c0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
185d0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
185e0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
185f0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
18600 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
18610 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
18620 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
18630 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
18640 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
18650 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
18660 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
18670 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
18680 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
18690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
186a0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
186b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
186c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
186d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
186e0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
186f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18700 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
18710 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
18720 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
18730 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
18740 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
18750 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
18760 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
18770 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
18780 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
18790 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
187a0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
187b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
187c0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
187d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
187e0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
187f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
18800 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18810 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
18820 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
18830 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
18840 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
18850 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
18860 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
18870 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
18880 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
18890 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
188a0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
188b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
188c0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
188d0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
188e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
188f0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
18900 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
18910 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
18920 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
18930 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
18940 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
18950 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
18960 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
18970 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
18980 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
18990 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
189a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
189b0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
189c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
189d0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
189e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
189f0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
18a00 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
18a10 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
18a20 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
18a30 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
18a40 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
18a50 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
18a60 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
18a70 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
18a80 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
18a90 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
18aa0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
18ab0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
18ac0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
18ad0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
18ae0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
18af0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
18b00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
18b10 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
18b20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
18b30 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
18b40 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
18b50 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
18b60 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
18b70 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
18b80 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
18b90 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
18ba0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
18bb0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
18bc0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
18bd0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
18be0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
18bf0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
18c00 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
18c10 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
18c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
18c30 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
18c40 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
18c50 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
18c60 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
18c70 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
18c80 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
18c90 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
18ca0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
18cb0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
18cc0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
18cd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
18ce0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
18cf0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
18d00 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
18d10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
18d20 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
18d30 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
18d40 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
18d50 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
18d60 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
18d70 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
18d80 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
18d90 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
18da0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
18db0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
18dc0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
18dd0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
18de0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
18df0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
18e00 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
18e10 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
18e20 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
18e30 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
18e40 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
18e50 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
18e60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18e70 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
18e80 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
18e90 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
18ea0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
18eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18ec0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
18ed0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
18ee0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
18ef0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
18f00 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
18f10 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
18f20 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
18f30 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
18f40 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
18f50 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
18f60 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
18f70 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
18f80 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
18f90 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
18fa0 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
18fb0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
18fc0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
18fd0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
18fe0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
18ff0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
19000 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
19010 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
19020 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
19030 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
19040 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
19050 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
19060 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
19070 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
19080 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
19090 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
190a0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
190b0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
190c0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
190d0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
190e0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
190f0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
19100 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
19110 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
19120 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
19130 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
19140 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
19150 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
19160 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
19170 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19180 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
19190 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
191a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
191b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
191c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
191d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
191e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
191f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
19200 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
19210 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
19220 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
19230 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
19240 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
19250 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
19260 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
19270 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
19280 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
19290 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
192a0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
192b0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
192c0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
192d0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
192e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
192f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19300 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
19310 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
19320 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
19330 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
19340 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
19350 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
19360 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
19370 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
19380 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
19390 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
193a0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
193b0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
193c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
193d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
193e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
193f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
19400 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
19410 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
19420 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
19430 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
19440 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
19450 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
19460 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
19470 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
19480 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
19490 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
194a0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
194b0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
194c0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
194d0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
194e0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
194f0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
19500 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
19510 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
19520 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
19530 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
19540 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
19550 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
19560 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
19570 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
19580 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
19590 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
195a0 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
195b0 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
195c0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
195d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
195e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
195f0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
19600 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
19610 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
19620 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
19630 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
19640 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
19650 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
19660 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
19670 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19680 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
19690 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
196a0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
196b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
196c0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
196d0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
196e0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
196f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
19700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
19710 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
19720 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
19730 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
19740 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
19750 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
19760 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
19770 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
19780 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
19790 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
197a0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
197b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
197c0 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
197d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
197e0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
197f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
19800 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
19810 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
19820 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
19830 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
19840 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
19850 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
19860 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
19870 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
19880 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
19890 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
198a0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
198b0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
198c0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
198d0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
198e0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
198f0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
19900 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
19910 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
19920 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
19930 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
19940 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
19950 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
19960 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
19970 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
19980 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
19990 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
199a0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
199b0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
199c0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
199d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
199e0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
199f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
19a00 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
19a10 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
19a20 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
19a30 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
19a40 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
19a50 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
19a60 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
19a70 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
19a80 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
19a90 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
19aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
19ab0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
19ac0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
19ad0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
19ae0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
19af0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
19b00 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
19b10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b20 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
19b30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
19b40 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
19b50 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
19b60 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
19b70 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
19b80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
19b90 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
19ba0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
19bb0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
19bc0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
19bd0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
19be0 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
19bf0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
19c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
19c10 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
19c20 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
19c30 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
19c40 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
19c50 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
19c60 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
19c70 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
19c80 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
19c90 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
19ca0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
19cb0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
19cc0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
19cd0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
19ce0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
19cf0 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
19d00 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
19d10 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
19d20 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
19d30 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
19d40 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
19d50 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
19d60 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
19d70 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
19d80 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
19d90 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
19da0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
19db0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
19dc0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
19dd0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
19de0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
19df0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
19e00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19e10 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
19e20 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
19e30 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
19e40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
19e50 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
19e60 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
19e70 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
19e80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
19e90 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
19ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19eb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
19ec0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
19ed0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
19ee0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
19ef0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
19f00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
19f10 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
19f20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19f30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
19f40 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
19f50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
19f60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19f70 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
19f80 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
19f90 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
19fa0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
19fb0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
19fc0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
19fd0 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
19fe0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
19ff0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1a000 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
1a010 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1a020 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1a030 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1a040 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1a050 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1a060 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1a070 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
1a080 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
1a090 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1a0a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1a0b0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1a0c0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1a0d0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1a0e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1a0f0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1a100 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1a110 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1a120 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1a130 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
1a140 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1a150 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1a160 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1a170 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
1a180 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
1a190 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
1a1a0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
1a1b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1a1c0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
1a1d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
1a1e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1a1f0 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
1a200 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1a210 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1a220 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1a230 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1a240 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1a250 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1a260 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1a270 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1a280 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1a290 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1a2a0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1a2b0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1a2c0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1a2d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1a2e0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1a2f0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1a300 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1a310 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1a320 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1a330 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1a340 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1a350 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1a360 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1a370 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1a380 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1a390 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1a3a0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1a3b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1a3c0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1a3d0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1a3e0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1a3f0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1a400 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1a410 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1a420 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1a430 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1a440 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1a450 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1a460 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1a470 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1a480 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1a490 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1a4a0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1a4b0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1a4c0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1a4d0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1a4e0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1a4f0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1a500 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1a510 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1a520 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1a530 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1a540 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1a550 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1a560 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1a570 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a580 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1a590 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1a5a0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1a5b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1a5c0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1a5d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a5e0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1a5f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1a600 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1a610 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1a620 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1a630 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1a640 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1a650 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1a660 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1a670 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1a680 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1a690 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1a6a0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1a6b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1a6c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1a6d0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1a6e0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1a6f0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1a700 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1a710 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1a720 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1a730 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1a740 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1a750 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1a760 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1a770 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1a780 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1a790 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1a7a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1a7b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1a7c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1a7d0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1a7e0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1a7f0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1a800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1a810 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1a820 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1a830 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1a840 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1a850 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1a860 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1a870 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1a880 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1a890 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1a8a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1a8b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1a8c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1a8d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1a8e0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1a8f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1a900 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1a910 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1a920 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1a930 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1a940 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1a950 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1a960 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1a970 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a980 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1a990 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1a9a0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1a9b0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1a9c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1a9d0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1a9e0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1a9f0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1aa00 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1aa10 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1aa20 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1aa30 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1aa40 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1aa50 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1aa60 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1aa70 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1aa80 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1aa90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1aaa0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1aab0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1aac0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1aad0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1aae0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1aaf0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1ab00 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1ab10 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ab20 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1ab30 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1ab40 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1ab50 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1ab60 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1ab70 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1ab80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ab90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1aba0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1abb0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1abc0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1abd0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1abe0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1abf0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1ac00 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1ac10 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1ac20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1ac30 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1ac40 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1ac50 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1ac60 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1ac70 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1ac80 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1ac90 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1aca0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1acb0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1acc0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1acd0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1ace0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1acf0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1ad00 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1ad10 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1ad20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1ad30 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1ad40 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1ad50 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1ad60 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1ad70 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1ad80 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1ad90 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1ada0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1adb0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1adc0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1add0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1ade0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1adf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ae00 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1ae10 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1ae20 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1ae30 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1ae40 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1ae50 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1ae60 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1ae70 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1ae80 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1ae90 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1aea0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1aeb0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1aec0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1aed0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1aee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1aef0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1af00 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1af10 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1af20 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1af30 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1af40 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1af50 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1af60 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1af70 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1af80 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1af90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1afa0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1afb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1afc0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1afd0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1afe0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1aff0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b000 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1b010 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1b020 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1b030 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1b040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1b050 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1b060 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b070 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1b080 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1b090 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1b0a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1b0b0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1b0c0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1b0d0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1b0e0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1b0f0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1b100 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1b110 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1b120 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1b130 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1b140 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1b150 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1b160 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1b170 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b180 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1b190 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1b1a0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1b1b0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1b1c0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1b1d0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1b1e0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1b1f0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1b200 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1b210 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1b220 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1b230 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1b240 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1b250 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1b260 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1b270 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1b280 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b290 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1b2a0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1b2b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1b2c0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1b2d0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1b2e0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1b2f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b300 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1b310 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1b320 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1b330 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1b340 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1b350 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1b360 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1b370 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1b380 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1b390 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1b3a0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1b3b0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1b3c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1b3d0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1b3e0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1b3f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b400 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1b410 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1b420 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1b430 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1b440 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1b450 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1b460 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1b470 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1b480 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1b490 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1b4a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b4b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1b4c0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1b4d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1b4e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b4f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1b500 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1b510 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1b520 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b530 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1b540 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1b550 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1b560 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1b570 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1b580 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1b590 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1b5a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1b5b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1b5c0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1b5d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1b5e0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1b5f0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1b600 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1b610 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1b620 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1b630 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1b640 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1b650 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1b660 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1b670 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1b680 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1b690 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1b6a0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1b6b0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1b6c0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1b6d0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1b6e0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1b6f0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1b700 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1b710 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1b720 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1b730 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1b740 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1b750 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1b760 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1b770 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1b780 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1b790 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1b7a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1b7b0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1b7c0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1b7d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b7e0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1b7f0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1b800 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1b810 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1b820 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1b830 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1b840 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1b850 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1b860 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1b870 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1b880 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1b890 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1b8a0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1b8b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b8c0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1b8d0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1b8e0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1b8f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b900 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1b910 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1b920 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1b930 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1b940 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1b950 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1b960 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1b970 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1b980 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1b990 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1b9a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1b9b0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1b9c0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1b9d0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1b9e0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1b9f0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1ba00 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1ba10 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1ba20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1ba30 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1ba40 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1ba50 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1ba60 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1ba70 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1ba80 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1ba90 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1baa0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1bab0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1bac0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1bad0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1bae0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1baf0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1bb00 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1bb10 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1bb20 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1bb30 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1bb40 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1bb50 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1bb60 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1bb70 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1bb80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1bb90 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1bba0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1bbb0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1bbc0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1bbd0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1bbe0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1bbf0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1bc00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1bc10 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1bc20 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1bc30 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1bc40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1bc50 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1bc60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1bc70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1bc80 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1bc90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1bca0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1bcb0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1bcc0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1bcd0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1bce0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1bcf0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1bd00 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1bd10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1bd20 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1bd30 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1bd40 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1bd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bd60 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1bd70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1bd80 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1bd90 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1bda0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1bdb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bdc0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1bdd0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1bde0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1bdf0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1be00 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1be10 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1be20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1be30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1be40 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1be50 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1be60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1be70 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1be80 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1be90 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1bea0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1beb0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1bec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1bed0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1bee0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1bef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1bf00 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1bf10 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1bf20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bf30 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1bf40 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1bf50 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1bf60 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1bf70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1bf80 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1bf90 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1bfa0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1bfb0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1bfc0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1bfd0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1bfe0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1bff0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1c000 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1c010 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1c020 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1c030 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1c040 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1c050 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1c060 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1c070 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1c080 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1c090 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1c0a0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1c0b0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1c0c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1c0d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1c0e0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c0f0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1c100 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1c110 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1c120 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1c130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1c140 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c150 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1c160 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c170 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1c180 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1c190 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1c1a0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1c1b0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1c1c0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1c1d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1c1e0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1c1f0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1c200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1c210 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1c220 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1c230 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1c240 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1c250 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1c260 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1c270 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1c280 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52  d as a [SQLITE_R
1c290 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e  OLLBACK | return
1c2a0 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74   code].** from t
1c2b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1c2c0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1c2d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1c2e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1c2f0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1c300 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c310 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1c320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c330 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1c340 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1c350 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1c360 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1c370 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1c380 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1c390 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1c3a0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1c3b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1c3c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1c3d0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1c3e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1c3f0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1c400 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1c410 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c420 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1c430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c440 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1c450 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1c460 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1c470 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1c480 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1c490 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1c4a0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1c4b0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1c4c0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1c4d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1c4e0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1c4f0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1c500 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1c510 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1c520 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1c530 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1c540 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1c550 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1c560 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1c570 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1c580 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1c590 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1c5a0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1c5b0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1c5c0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1c5d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1c5e0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1c5f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1c600 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1c610 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1c620 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1c630 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1c640 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1c650 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1c660 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1c670 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1c680 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c690 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1c6a0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1c6b0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1c6c0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1c6d0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1c6e0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1c6f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1c700 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1c710 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1c720 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1c730 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1c740 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c750 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c760 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1c770 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1c780 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1c790 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1c7a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1c7b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c7c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c7d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c7e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1c7f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1c800 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c810 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c820 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c830 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c840 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1c850 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1c860 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c870 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c880 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c890 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1c8a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c8b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c8c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c8d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1c8e0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1c8f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c900 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c920 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1c930 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1c940 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c950 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c970 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1c980 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1c990 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1c9a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c9b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c9c0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1c9d0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1c9e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1c9f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ca00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ca10 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1ca20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1ca30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ca40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ca50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ca60 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1ca70 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1ca80 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ca90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1caa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1cab0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1cac0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1cad0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1cae0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1caf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1cb00 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1cb10 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1cb20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1cb30 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1cb40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1cb50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1cb60 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1cb70 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1cb80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cb90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1cba0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1cbb0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1cbc0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1cbd0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1cbe0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1cbf0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1cc00 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1cc10 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1cc20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1cc30 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1cc40 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1cc50 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1cc60 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1cc70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cc80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1cc90 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1cca0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ccb0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ccc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ccd0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1cce0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1ccf0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1cd00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1cd10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cd20 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1cd30 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1cd40 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1cd50 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1cd60 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1cd70 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1cd80 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1cd90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1cda0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1cdb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cdc0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1cdd0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1cde0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cdf0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ce00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ce10 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1ce20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1ce30 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1ce40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ce50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ce60 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1ce70 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1ce80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1ce90 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1cea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ceb0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1cec0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1ced0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1cee0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1cef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cf00 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1cf10 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1cf20 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1cf30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cf40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1cf50 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1cf60 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1cf70 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1cf80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1cf90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1cfa0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1cfb0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1cfc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1cfd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cfe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1cff0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1d000 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1d010 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d020 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d030 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d040 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1d050 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1d060 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1d070 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1d080 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d090 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1d0a0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1d0b0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1d0c0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1d0d0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1d0e0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1d0f0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1d100 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1d110 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1d120 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1d130 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1d140 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1d150 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1d160 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1d170 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1d180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1d190 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1d1a0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
1d1b0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1d1c0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1d1d0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1d1e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1d1f0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1d200 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1d210 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1d220 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1d230 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1d240 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1d250 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1d260 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1d270 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1d280 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1d290 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1d2a0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1d2b0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1d2c0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1d2d0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1d2e0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1d2f0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1d300 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1d310 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1d320 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1d330 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1d340 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1d350 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1d360 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1d370 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1d380 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1d390 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1d3a0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1d3b0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1d3c0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1d3d0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1d3e0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1d3f0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1d400 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1d410 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1d420 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1d430 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1d440 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1d450 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1d460 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1d470 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1d480 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1d490 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1d4a0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1d4b0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1d4c0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1d4d0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1d4e0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1d4f0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1d500 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1d510 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1d520 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1d530 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1d540 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1d550 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1d560 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1d570 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1d580 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1d590 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1d5a0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1d5b0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1d5c0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1d5d0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1d5e0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1d5f0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1d600 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1d610 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1d620 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1d630 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1d640 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1d650 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1d660 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1d670 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1d680 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1d690 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1d6a0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1d6b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d6c0 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1d6d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1d6e0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1d6f0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1d700 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1d710 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1d720 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1d730 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1d740 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1d750 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1d760 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1d770 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1d780 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d790 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1d7a0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1d7b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d7c0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1d7d0 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1d7e0 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1d7f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1d800 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1d810 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1d820 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1d830 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1d840 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1d850 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1d860 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1d870 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1d880 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1d890 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1d8a0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1d8b0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1d8c0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1d8d0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1d8e0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1d900 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1d910 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1d920 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1d930 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1d940 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1d950 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1d960 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72   N is the number
1d970 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1d980 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1d990 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1d9a0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
1d9b0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
1d9c0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1d9d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a  he callback X..*
1d9e0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
1d9f0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
1da00 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
1da10 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
1da20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
1da30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
1da40 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
1da50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
1da60 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
1da70 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
1da80 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
1da90 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
1daa0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1dab0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
1dac0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
1dad0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
1dae0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
1daf0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
1db00 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
1db10 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1db20 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1db30 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1db40 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1db50 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1db60 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1db70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1db80 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1db90 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1dba0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1dbb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1dbc0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
1dbd0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1dbe0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1dbf0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1dc00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dc10 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1dc20 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
1dc30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
1dc40 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1dc50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1dc60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dc70 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1dc80 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1dc90 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1dca0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1dcb0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1dcc0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
1dcd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1dce0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1dcf0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1dd00 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1dd10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1dd20 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1dd30 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1dd40 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
1dd50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
1dd60 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
1dd70 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
1dd80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
1dd90 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1dda0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1ddb0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1ddc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1ddd0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1dde0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1ddf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1de00 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1de10 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1de20 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1de30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1de40 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1de50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1de60 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1de70 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1de80 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1de90 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1dea0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1deb0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1dec0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1ded0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1dee0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1def0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1df00 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1df10 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1df20 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1df30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1df40 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1df50 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1df60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1df70 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1df80 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1df90 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1dfa0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1dfb0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1dfc0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1dfd0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1dfe0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1dff0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1e000 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1e010 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1e020 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1e030 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1e040 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1e050 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1e060 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1e070 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1e080 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1e090 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1e0a0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1e0b0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1e0c0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1e0d0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1e0e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1e0f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e100 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1e110 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1e120 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1e130 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1e140 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1e150 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1e160 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1e170 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1e180 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1e190 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1e1a0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1e1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e1c0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1e1d0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1e1e0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1e1f0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1e200 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1e210 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1e220 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1e230 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1e240 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1e250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1e260 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1e270 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1e280 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1e290 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1e2a0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1e2b0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1e2c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1e2d0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1e2e0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1e2f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1e300 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1e310 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1e320 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1e330 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1e340 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1e350 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1e360 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1e370 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1e380 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1e390 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
1e3a0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1e3b0 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
1e3c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
1e3d0 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1e3e0 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1e3f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1e400 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1e410 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1e420 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1e430 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1e440 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1e450 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1e460 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1e470 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1e480 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1e490 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1e4a0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1e4b0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1e4c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1e4d0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1e4e0 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1e4f0 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1e500 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1e510 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1e520 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1e530 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1e540 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1e550 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1e560 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1e570 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1e580 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1e590 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e5a0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1e5b0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1e5c0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1e5d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e5e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e5f0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1e600 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1e610 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
1e620 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1e630 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1e640 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1e650 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1e660 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1e670 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1e680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1e6a0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1e6b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1e6c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e6d0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1e6e0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1e6f0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1e700 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1e710 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
1e720 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
1e730 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
1e740 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
1e750 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1e760 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1e770 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1e780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1e790 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1e7a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1e7b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1e7c0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1e7d0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1e7e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1e7f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1e800 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1e810 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1e820 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1e830 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1e840 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1e850 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1e860 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1e870 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1e880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1e890 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1e8a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1e8b0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1e8c0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1e8d0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1e8e0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1e8f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1e900 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1e910 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1e920 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1e930 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1e940 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e950 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1e960 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1e970 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1e980 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1e990 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1e9a0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1e9b0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1e9c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1e9d0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1e9e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1e9f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1ea00 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1ea10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ea20 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1ea30 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1ea40 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1ea50 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1ea60 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1ea70 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1ea80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ea90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1eaa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1eab0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1eac0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1ead0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1eae0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1eaf0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1eb00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1eb10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1eb20 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1eb30 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1eb40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1eb50 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1eb60 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1eb70 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1eb80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1eb90 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1eba0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1ebb0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1ebc0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1ebd0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1ebe0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1ebf0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1ec00 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1ec10 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1ec20 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1ec30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1ec40 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1ec50 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1ec60 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1ec70 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1ec80 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1ec90 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1eca0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1ecb0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1ecc0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1ecd0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1ece0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1ecf0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1ed00 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1ed10 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1ed20 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1ed30 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1ed40 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1ed50 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1ed60 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1ed70 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1ed80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1ed90 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1eda0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1edb0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1edc0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1edd0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1ede0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1edf0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1ee00 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1ee10 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1ee20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1ee30 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
1ee40 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
1ee50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
1ee60 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
1ee70 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
1ee80 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
1ee90 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
1eea0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
1eeb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1eec0 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
1eed0 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
1eee0 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
1eef0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1ef00 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
1ef10 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
1ef20 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1ef30 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
1ef40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1ef50 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
1ef60 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
1ef70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
1ef80 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
1ef90 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
1efa0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
1efb0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
1efc0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
1efd0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
1efe0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1eff0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
1f000 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
1f010 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
1f020 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
1f030 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
1f040 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
1f050 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1f060 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
1f070 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
1f080 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
1f090 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
1f0a0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
1f0b0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
1f0c0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
1f0d0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
1f0e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
1f0f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1f100 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1f110 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
1f120 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
1f130 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
1f140 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
1f150 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
1f160 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
1f170 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
1f180 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1f190 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
1f1a0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
1f1b0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1f1c0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
1f1d0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
1f1e0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
1f1f0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1f200 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
1f210 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
1f220 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1f230 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
1f240 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
1f250 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
1f260 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
1f270 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
1f280 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
1f290 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
1f2a0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
1f2b0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
1f2c0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
1f2d0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
1f2e0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
1f2f0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
1f300 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
1f310 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
1f320 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
1f330 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
1f340 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
1f350 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
1f360 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
1f370 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
1f380 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
1f390 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1f3a0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
1f3b0 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
1f3c0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
1f3d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
1f3e0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
1f3f0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
1f400 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
1f410 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
1f420 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
1f430 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
1f440 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1f450 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
1f460 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
1f470 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
1f480 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
1f490 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
1f4a0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
1f4b0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
1f4c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
1f4d0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
1f4e0 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
1f4f0 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
1f500 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
1f510 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
1f520 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
1f530 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
1f540 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
1f550 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
1f560 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
1f570 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
1f580 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
1f590 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1f5a0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
1f5b0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
1f5c0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1f5d0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
1f5e0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
1f5f0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
1f600 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
1f610 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
1f620 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
1f630 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
1f640 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
1f650 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
1f660 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
1f670 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1f680 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
1f690 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
1f6a0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
1f6b0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
1f6c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
1f6d0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
1f6e0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
1f6f0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
1f700 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f710 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1f720 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
1f730 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
1f740 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
1f750 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
1f760 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
1f770 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
1f780 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
1f790 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
1f7a0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
1f7b0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
1f7c0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
1f7d0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
1f7e0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
1f7f0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1f800 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f810 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
1f820 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
1f830 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
1f840 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1f850 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
1f860 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
1f870 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1f880 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  to sqlite3_prepa
1f890 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  re_v2(). ^If the
1f8a0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
1f8b0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
1f8c0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
1f8d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1f8e0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
1f8f0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
1f900 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
1f910 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
1f920 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
1f930 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
1f940 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
1f950 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
1f960 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
1f970 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1f980 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
1f990 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
1f9a0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
1f9b0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
1f9c0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
1f9d0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
1f9e0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
1f9f0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
1fa00 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
1fa10 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
1fa20 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
1fa30 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
1fa40 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
1fa50 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
1fa60 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
1fa70 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
1fa80 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
1fa90 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
1faa0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
1fab0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
1fac0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
1fad0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
1fae0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1faf0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
1fb00 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
1fb10 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
1fb20 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1fb30 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1fb40 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
1fb50 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
1fb60 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
1fb70 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
1fb80 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1fb90 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
1fba0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1fbb0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
1fbc0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
1fbd0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
1fbe0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1fbf0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
1fc00 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
1fc10 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
1fc20 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
1fc30 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
1fc40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1fc50 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
1fc60 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
1fc70 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1fc80 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
1fc90 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
1fca0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
1fcb0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
1fcc0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
1fcd0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
1fce0 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
1fcf0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
1fd00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1fd10 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
1fd20 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1fd30 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
1fd40 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
1fd50 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
1fd60 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1fd70 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1fd80 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
1fd90 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
1fda0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1fdb0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
1fdc0 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
1fdd0 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
1fde0 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
1fdf0 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
1fe00 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
1fe10 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
1fe20 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
1fe30 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1fe40 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
1fe50 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
1fe60 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
1fe70 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
1fe80 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
1fe90 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
1fea0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
1feb0 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
1fec0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
1fed0 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
1fee0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
1fef0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
1ff00 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
1ff10 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
1ff20 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
1ff30 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
1ff40 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
1ff50 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
1ff60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1ff70 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
1ff80 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
1ff90 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1ffa0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
1ffb0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
1ffc0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1ffd0 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
1ffe0 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
1fff0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
20000 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
20010 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
20020 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
20030 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20040 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
20050 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
20060 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
20070 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
20080 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
20090 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
200a0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
200b0 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
200c0 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
200d0 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
200e0 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
200f0 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
20100 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
20110 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
20120 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
20130 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
20140 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
20150 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
20160 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
20170 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
20180 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
20190 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
201a0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
201b0 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
201c0 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
201d0 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
201e0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
201f0 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
20200 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
20210 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
20220 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
20230 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
20240 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
20250 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
20260 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
20270 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
20280 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
20290 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
202a0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
202b0 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
202c0 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
202d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
202e0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
202f0 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
20300 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
20310 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
20320 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20330 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
20340 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
20350 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
20360 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
20370 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
20380 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
20390 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
203a0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
203b0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
203c0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
203d0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
203e0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
203f0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
20400 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
20410 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
20420 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
20430 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
20440 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
20450 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
20460 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
20470 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
20480 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
20490 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
204a0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
204b0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
204c0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
204d0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
204e0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
204f0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
20500 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
20510 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
20520 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
20530 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
20540 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
20550 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
20560 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
20570 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
20580 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
20590 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
205a0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
205b0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
205c0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
205d0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
205e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
205f0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
20600 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
20610 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
20620 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
20630 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
20640 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
20650 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
20660 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
20670 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
20680 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
20690 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
206a0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
206b0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
206c0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
206d0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
206e0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
206f0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
20700 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
20710 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
20720 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
20730 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
20740 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
20750 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
20760 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
20770 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
20780 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
20790 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
207a0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
207b0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
207c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
207d0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
207e0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
207f0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
20800 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
20810 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
20820 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
20830 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20840 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
20850 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
20860 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
20870 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
20880 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
20890 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
208a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
208b0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
208c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
208d0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
208e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
208f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
20900 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
20910 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
20920 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
20930 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
20940 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
20950 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
20960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
20970 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
20980 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
20990 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
209a0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
209b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
209c0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
209d0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
209e0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
209f0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
20a00 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
20a10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
20a20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
20a30 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
20a40 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
20a50 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
20a60 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
20a70 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
20a80 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
20a90 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
20aa0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
20ab0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
20ac0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
20ad0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
20ae0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
20af0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
20b00 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
20b10 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
20b20 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
20b30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
20b40 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
20b50 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
20b60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20b70 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
20b80 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
20b90 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
20ba0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
20bb0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
20bc0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
20bd0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
20be0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
20bf0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
20c00 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
20c10 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
20c20 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
20c30 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
20c40 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
20c50 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
20c60 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
20c70 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
20c80 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
20c90 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
20ca0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
20cb0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
20cc0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
20cd0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
20ce0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
20cf0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
20d00 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
20d10 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
20d20 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
20d30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
20d40 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
20d50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
20d60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
20d70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
20d80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
20d90 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
20da0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
20db0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
20dc0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
20dd0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
20de0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
20df0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
20e00 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
20e10 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
20e20 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
20e30 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
20e40 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
20e50 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
20e60 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
20e70 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
20e80 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
20e90 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
20ea0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
20eb0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
20ec0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
20ed0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
20ee0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
20ef0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
20f00 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
20f10 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
20f20 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
20f30 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
20f40 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
20f50 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
20f60 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
20f70 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
20f80 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
20f90 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
20fa0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
20fb0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
20fc0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
20fd0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
20fe0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
20ff0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
21000 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
21010 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
21020 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
21030 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
21040 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
21050 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
21060 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
21070 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
21080 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
21090 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
210a0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
210b0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
210c0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
210d0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
210e0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
210f0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
21100 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
21110 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
21120 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
21130 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
21140 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
21150 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
21160 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
21170 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
21180 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
21190 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
211a0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
211b0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
211c0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
211d0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
211e0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
211f0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
21200 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
21210 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
21220 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
21230 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
21240 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
21250 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
21260 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
21270 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
21280 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
21290 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
212a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
212b0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
212c0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
212d0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
212e0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
212f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
21300 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
21310 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
21320 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
21330 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
21340 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
21350 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
21360 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
21370 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
21380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
21390 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
213a0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
213b0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
213c0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
213d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
213e0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
213f0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
21400 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
21410 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21420 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
21430 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
21440 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
21450 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
21460 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
21470 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
21480 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
21490 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
214a0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
214b0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
214c0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
214d0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
214e0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
214f0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
21500 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
21510 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
21520 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
21530 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
21540 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
21550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
21560 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
21570 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
21580 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
21590 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
215a0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
215b0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
215c0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
215d0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
215e0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
215f0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
21600 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
21610 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
21620 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
21630 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
21640 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
21650 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
21660 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
21670 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
21680 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
21690 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
216a0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
216b0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
216c0 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
216d0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
216e0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
216f0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
21700 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
21710 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
21720 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
21730 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
21740 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
21750 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
21760 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
21770 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
21780 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
21790 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
217a0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
217b0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
217c0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
217d0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
217e0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
217f0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
21800 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
21810 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
21820 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
21830 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
21840 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
21850 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
21860 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
21870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
21880 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
21890 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
218a0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
218b0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
218c0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
218d0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
218e0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
218f0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
21900 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
21910 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
21920 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
21930 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
21940 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
21950 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
21960 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
21970 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
21980 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
21990 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
219a0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
219b0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
219c0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
219d0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
219e0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
219f0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
21a00 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
21a10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
21a20 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
21a30 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
21a40 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
21a50 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
21a60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21a70 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
21a80 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
21a90 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
21aa0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
21ab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
21ac0 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
21ad0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
21ae0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
21af0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
21b00 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
21b10 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
21b20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
21b30 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
21b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
21b50 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
21b60 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
21b70 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
21b80 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
21b90 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
21ba0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
21bb0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
21bc0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
21bd0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
21be0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
21bf0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
21c00 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
21c10 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
21c20 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
21c30 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
21c40 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
21c50 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
21c60 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
21c70 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
21c80 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
21c90 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
21ca0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
21cb0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
21cc0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
21cd0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
21ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21cf0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
21d00 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
21d10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
21d20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
21d30 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
21d40 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
21d50 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
21d60 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
21d70 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
21d80 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
21d90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
21da0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
21db0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
21dc0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
21dd0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
21de0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
21df0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
21e00 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
21e10 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
21e20 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
21e30 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
21e40 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
21e50 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
21e60 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
21e70 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
21e80 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
21e90 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
21ea0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
21eb0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
21ec0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
21ed0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21ee0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
21ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21f00 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
21f10 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
21f20 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
21f30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
21f40 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
21f50 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
21f60 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
21f70 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
21f80 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
21f90 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
21fa0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
21fb0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
21fc0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
21fd0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
21fe0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
21ff0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
22000 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
22010 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
22020 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
22030 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
22040 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
22050 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
22060 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
22070 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
22080 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
22090 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
220a0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
220b0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
220c0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
220d0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
220e0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
220f0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
22100 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
22110 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
22120 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
22130 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
22140 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
22150 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
22160 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
22170 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
22180 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
22190 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
221a0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
221b0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
221c0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
221d0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
221e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
221f0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
22200 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
22210 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
22220 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
22230 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
22240 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
22250 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
22260 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
22270 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
22280 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
22290 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
222a0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
222b0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
222c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
222d0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
222e0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
222f0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
22300 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
22310 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
22320 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
22330 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
22340 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
22350 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
22360 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
22370 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
22380 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
22390 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
223a0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
223b0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
223c0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
223d0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
223e0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
223f0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
22400 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
22410 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
22420 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
22430 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
22440 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
22450 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
22460 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
22470 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
22480 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
22490 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
224a0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
224b0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
224c0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
224d0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
224e0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
224f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
22500 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
22510 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
22520 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
22530 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
22540 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
22550 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
22560 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
22570 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
22580 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
22590 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
225a0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
225b0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
225c0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
225d0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
225e0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
225f0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
22600 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
22610 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
22620 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
22630 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
22640 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
22650 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
22660 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
22670 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
22680 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
22690 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
226a0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
226b0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
226c0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
226d0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
226e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
226f0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
22700 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
22710 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
22720 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
22730 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
22740 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
22750 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
22760 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
22770 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
22780 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
22790 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
227a0 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
227b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
227c0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
227d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
227e0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
227f0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
22800 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
22810 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
22820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
22830 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
22840 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
22850 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
22860 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
22870 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
22880 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
22890 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
228a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
228b0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
228c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
228d0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
228e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
228f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
22900 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
22910 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
22920 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
22930 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
22940 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22950 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
22960 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
22970 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
22980 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
22990 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
229a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
229b0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
229c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
229d0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
229e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
229f0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
22a00 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
22a10 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
22a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22a30 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
22a40 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
22a50 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
22a60 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
22a70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22a80 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
22a90 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
22aa0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
22ab0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
22ac0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
22ad0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
22ae0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22af0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
22b00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22b10 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
22b20 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
22b30 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
22b40 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
22b50 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
22b60 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
22b70 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
22b80 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
22b90 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
22ba0 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
22bb0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
22bc0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
22bd0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22be0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
22bf0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
22c00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
22c10 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
22c20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
22c30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
22c40 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
22c50 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
22c60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22c70 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
22c80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
22c90 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
22ca0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22cb0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
22cc0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
22cd0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
22ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
22cf0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
22d00 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
22d10 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22d20 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
22d30 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
22d40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
22d50 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
22d60 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
22d70 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
22d80 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
22d90 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
22da0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22db0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
22dc0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
22dd0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
22de0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
22df0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22e00 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
22e10 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
22e20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
22e30 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
22e40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
22e50 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
22e60 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
22e70 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
22e80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
22e90 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
22ea0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
22eb0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
22ec0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
22ed0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
22ee0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
22ef0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
22f00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
22f10 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
22f20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
22f30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22f40 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
22f50 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
22f60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22f70 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
22f80 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
22f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22fa0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
22fb0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
22fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22fd0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
22fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
22ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23000 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
23010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
23020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23030 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
23040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
23050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23060 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
23070 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
23080 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
23090 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
230a0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
230b0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
230c0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
230d0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
230e0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
230f0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
23100 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
23110 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
23120 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
23130 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
23140 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
23150 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
23160 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
23170 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
23180 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
23190 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
231a0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
231b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
231c0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
231d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
231e0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
231f0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
23200 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
23210 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
23220 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
23230 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
23240 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
23250 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
23260 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
23270 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
23280 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
23290 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
232a0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
232b0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
232c0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
232d0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
232e0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
232f0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
23300 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
23310 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
23320 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
23330 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
23340 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
23350 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
23360 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
23370 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
23380 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
23390 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
233a0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
233b0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
233c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
233d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
233e0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
233f0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
23400 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
23410 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
23420 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
23430 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
23440 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
23450 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
23460 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
23470 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
23480 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
23490 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
234a0 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
234b0 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
234c0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
234d0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
234e0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
234f0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
23500 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
23510 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
23520 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
23530 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
23540 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
23550 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
23560 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
23570 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
23580 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23590 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
235a0 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
235b0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
235c0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
235d0 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
235e0 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
235f0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
23600 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
23610 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
23620 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
23630 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
23640 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
23650 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
23660 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
23670 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
23680 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
23690 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
236a0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
236b0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
236c0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
236d0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
236e0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
236f0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
23700 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
23710 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
23720 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
23730 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
23740 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23750 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
23760 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
23770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
23780 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
23790 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
237a0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
237b0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
237c0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
237d0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
237e0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
237f0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
23800 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
23810 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
23820 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
23830 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
23840 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
23850 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
23860 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
23870 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
23880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
23890 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
238a0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
238b0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
238c0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
238d0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
238e0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
238f0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
23900 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
23910 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
23920 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
23930 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
23940 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
23950 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
23960 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
23970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23980 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
23990 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
239a0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
239b0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
239c0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
239d0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
239e0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
239f0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
23a00 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
23a10 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
23a20 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
23a30 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
23a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23a50 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
23a60 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
23a70 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
23a80 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
23a90 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
23aa0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
23ab0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
23ac0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23ad0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
23ae0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
23af0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
23b00 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
23b10 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
23b20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
23b30 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
23b40 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
23b50 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
23b60 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
23b70 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
23b80 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
23b90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
23ba0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
23bb0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
23bc0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
23bd0 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  gain..** </li>.*
23be0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
23bf0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
23c00 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
23c10 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
23c20 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
23c30 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
23c40 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
23c50 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
23c60 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
23c70 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
23c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
23c90 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
23ca0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
23cb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
23cc0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
23cd0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
23ce0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
23cf0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
23d00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
23d10 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
23d20 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
23d30 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
23d40 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
23d50 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
23d60 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
23d70 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
23d80 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
23d90 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
23da0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
23db0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
23dc0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
23dd0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
23de0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
23df0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
23e00 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
23e10 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
23e20 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
23e30 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
23e40 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
23e50 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
23e60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
23e70 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
23e80 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
23e90 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
23ea0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
23eb0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
23ec0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
23ed0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
23ee0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
23ef0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
23f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
23f10 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
23f20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
23f30 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
23f40 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
23f50 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
23f60 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
23f70 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
23f80 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
23f90 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
23fa0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
23fb0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
23fc0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
23fd0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
23fe0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
23ff0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
24000 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
24010 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
24020 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
24030 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
24040 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
24050 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c  ..** the .** </l
24060 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
24070 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
24080 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
24090 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
240a0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
240b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
240c0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
240d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
240e0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
240f0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
24100 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
24110 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24120 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
24130 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
24140 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
24150 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
24160 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24170 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
24180 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
24190 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
241a0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
241b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
241c0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
241d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
241e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
241f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
24200 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
24210 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
24220 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
24230 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
24240 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
24250 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
24260 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
24270 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
24280 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
24290 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
242a0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
242b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
242c0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
242d0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
242e0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
242f0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
24300 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
24310 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
24320 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
24330 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
24340 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
24350 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
24360 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
24370 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
24380 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
24390 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
243a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
243b0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
243c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
243d0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
243e0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
243f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
24400 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
24410 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
24420 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
24430 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
24440 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
24450 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
24460 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
24470 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
24480 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24490 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
244a0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
244b0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
244c0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
244d0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
244e0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
244f0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
24500 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
24510 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
24520 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
24530 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
24540 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
24550 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
24560 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
24570 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
24580 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
24590 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
245a0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
245b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
245c0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
245d0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
245e0 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
245f0 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
24600 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
24610 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
24620 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
24630 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
24640 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
24650 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
24660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24670 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24680 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
24690 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
246a0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
246b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
246c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
246d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
246e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
246f0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
24700 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
24710 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
24720 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
24730 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
24740 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
24750 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
24760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24770 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
24780 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
24790 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
247a0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
247b0 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
247c0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
247d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
247e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
247f0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
24800 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
24810 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
24820 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
24830 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
24840 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
24850 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
24860 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
24870 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
24880 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
24890 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
248a0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
248b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
248c0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
248d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
248e0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
248f0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
24900 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
24910 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
24920 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
24930 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
24940 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
24950 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
24960 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
24970 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
24980 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
24990 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
249a0 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
249b0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
249c0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
249d0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
249e0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
249f0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
24a00 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
24a10 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
24a20 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
24a30 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
24a40 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
24a50 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24a60 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
24a70 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
24a80 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
24a90 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
24aa0 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
24ab0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
24ac0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
24ad0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
24ae0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
24af0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
24b00 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
24b10 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
24b20 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
24b30 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
24b40 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
24b50 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
24b60 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
24b70 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
24b80 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
24b90 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
24ba0 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
24bb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24bc0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
24bd0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
24be0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
24bf0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
24c00 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
24c10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
24c20 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
24c30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
24c40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24c50 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
24c60 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
24c70 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
24c80 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
24c90 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
24ca0 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
24cb0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
24cc0 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
24cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24ce0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
24cf0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
24d00 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
24d10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
24d20 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
24d30 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
24d40 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
24d50 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
24d60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
24d70 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
24d80 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24d90 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
24da0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
24db0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
24dc0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
24dd0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
24de0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
24df0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
24e00 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
24e10 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
24e20 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
24e30 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
24e40 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
24e50 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
24e60 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
24e70 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
24e80 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
24e90 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
24ea0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
24eb0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
24ec0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
24ed0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
24ee0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
24ef0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
24f00 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
24f10 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
24f20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
24f30 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
24f40 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
24f50 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
24f60 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
24f70 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
24f80 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
24f90 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
24fa0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
24fb0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
24fc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24fd0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
24fe0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
24ff0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
25000 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
25010 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
25020 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25030 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
25040 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
25050 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25060 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
25070 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
25080 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
25090 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
250a0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
250b0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
250c0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
250d0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
250e0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
250f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25100 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
25110 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
25120 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
25130 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
25140 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
25150 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
25160 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
25170 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
25180 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
25190 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
251a0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
251b0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
251c0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
251d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
251e0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
251f0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
25200 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
25210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
25220 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
25230 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
25240 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
25250 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
25260 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
25270 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
25280 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
25290 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
252a0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
252b0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
252c0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
252d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
252e0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
252f0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
25300 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
25310 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
25320 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25330 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
25340 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
25350 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
25360 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25370 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
25380 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
25390 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
253a0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
253b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
253c0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
253d0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
253e0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
253f0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
25400 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
25410 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
25420 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
25430 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
25440 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
25450 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
25460 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
25470 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
25480 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
25490 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
254a0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
254b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
254c0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
254d0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
254e0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
254f0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
25500 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
25510 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
25520 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
25530 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
25540 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
25550 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
25560 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
25570 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
25580 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
25590 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
255a0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
255b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
255c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
255d0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
255e0 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
255f0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
25600 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
25610 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
25630 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
25640 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
25650 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
25660 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
25670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25680 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
25690 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
256a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
256b0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
256c0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
256d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
256e0 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
256f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
25700 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
25710 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
25720 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
25730 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
25740 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
25750 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
25760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25770 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
25780 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
25790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
257a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
257b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
257c0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
257d0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
257e0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
257f0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
25800 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
25810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
25820 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
25830 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
25840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
25850 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
25860 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
25870 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
25880 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
25890 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
258a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
258b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
258c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
258d0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
258e0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
258f0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
25900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
25910 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
25920 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
25930 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
25940 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
25950 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
25960 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
25970 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
25980 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
25990 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
259a0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
259b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
259c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
259d0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
259e0 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
259f0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
25a00 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
25a10 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
25a20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
25a30 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
25a40 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
25a50 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
25a60 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
25a70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
25a80 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
25a90 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
25aa0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
25ab0 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
25ac0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
25ad0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
25ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25af0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
25b00 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
25b10 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
25b20 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
25b30 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
25b40 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
25b50 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
25b60 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
25b70 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
25b80 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
25b90 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
25ba0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
25bb0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
25bc0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
25bd0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
25be0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
25bf0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
25c00 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
25c10 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
25c20 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
25c30 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
25c40 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
25c50 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
25c60 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
25c70 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
25c80 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
25c90 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
25ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25cb0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
25cc0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
25cd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
25ce0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
25cf0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
25d00 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
25d10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25d20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
25d30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
25d40 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
25d50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25d60 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
25d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
25d80 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
25d90 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
25da0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
25db0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
25dc0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
25dd0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
25de0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
25df0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
25e00 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
25e10 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
25e20 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
25e30 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
25e40 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
25e50 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
25e60 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
25e70 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
25e80 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
25e90 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
25ea0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
25eb0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
25ec0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25ed0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
25ee0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
25ef0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
25f00 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
25f10 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
25f20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
25f30 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
25f40 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
25f50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
25f60 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
25f70 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
25f80 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25f90 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
25fa0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
25fb0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
25fc0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
25fd0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
25fe0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
25ff0 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
26000 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
26010 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
26020 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
26030 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
26040 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
26050 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
26060 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
26070 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
26080 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
26090 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
260a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
260b0 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
260c0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
260d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
260e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
260f0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
26100 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
26110 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
26120 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
26130 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
26140 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26150 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
26160 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
26170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
26180 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
261a0 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
261b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
261c0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
261d0 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
261e0 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
261f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
26200 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
26210 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
26220 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
26230 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
26240 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
26250 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
26260 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
26270 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
26280 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
26290 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
262a0 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
262b0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
262c0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
262d0 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
262e0 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
262f0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
26300 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
26310 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
26320 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
26330 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
26340 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
26350 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
26360 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
26370 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
26380 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
26390 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
263a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
263b0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
263c0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
263d0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
263e0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
263f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
26400 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
26410 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
26420 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
26430 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
26440 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
26450 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
26460 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
26470 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
26480 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
26490 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
264a0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
264b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
264c0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
264d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
264e0 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
264f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
26500 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
26510 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
26520 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
26530 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
26540 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
26550 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
26560 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
26570 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
26580 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
26590 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
265a0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
265b0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
265c0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
265d0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
265e0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
265f0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
26600 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
26610 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
26620 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
26630 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
26640 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
26650 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
26660 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
26670 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
26680 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
26690 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
266a0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
266b0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
266c0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
266d0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
266e0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
266f0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
26700 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
26710 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
26720 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
26730 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
26740 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
26750 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
26760 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
26770 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
26780 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
26790 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
267a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
267b0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
267c0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
267d0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
267e0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
267f0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
26800 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
26810 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
26820 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
26830 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
26840 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
26850 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
26860 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
26870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26880 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
26890 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
268a0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
268b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
268c0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
268d0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
268e0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
268f0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
26900 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
26910 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
26920 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
26930 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
26940 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
26950 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
26960 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
26970 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
26980 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
26990 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
269a0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
269b0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
269c0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
269d0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
269e0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
269f0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
26a00 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
26a10 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
26a20 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
26a30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
26a40 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
26a50 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
26a60 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
26a70 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
26a80 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
26a90 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
26aa0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
26ab0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
26ac0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
26ad0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
26ae0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
26af0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
26b00 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
26b10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
26b20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26b30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
26b40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26b50 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
26b60 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
26b70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
26b80 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
26b90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26ba0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26bb0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
26bc0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
26bd0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
26be0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
26bf0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26c00 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
26c10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26c20 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
26c30 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
26c40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
26c50 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
26c60 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
26c70 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
26c80 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
26c90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26ca0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
26cb0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
26cc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
26cd0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
26ce0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
26cf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
26d00 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
26d10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
26d20 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
26d30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
26d40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
26d50 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
26d60 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
26d70 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
26d80 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
26d90 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
26da0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26db0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
26dc0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
26dd0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
26de0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
26df0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
26e00 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
26e10 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
26e20 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
26e30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26e40 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
26e50 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
26e60 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
26e70 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
26e80 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
26e90 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
26ea0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
26eb0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
26ec0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
26ed0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
26ee0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
26ef0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
26f00 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
26f10 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
26f20 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
26f30 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
26f40 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
26f50 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
26f60 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
26f70 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
26f80 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
26f90 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
26fa0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
26fb0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
26fc0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
26fd0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
26fe0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
26ff0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
27000 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
27010 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27020 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27030 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27050 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
27060 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
27070 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27080 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
27090 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
270a0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
270b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
270c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
270d0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
270e0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
270f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
27100 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
27110 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
27120 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
27130 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
27140 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
27150 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
27160 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
27170 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
27180 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
27190 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
271a0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
271b0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
271c0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
271d0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
271e0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
271f0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
27200 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
27210 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
27220 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
27230 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
27240 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
27250 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
27260 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
27270 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
27280 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
27290 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
272a0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
272b0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
272c0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
272d0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
272e0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
272f0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
27300 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
27310 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
27320 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
27330 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
27340 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
27350 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
27360 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
27370 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
27380 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
27390 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
273a0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
273b0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
273c0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
273d0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
273e0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
273f0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
27400 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
27410 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27420 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
27430 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27440 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
27450 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
27460 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
27470 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
27480 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27490 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
274a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
274b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
274c0 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
274d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
274e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
274f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27500 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27510 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
27520 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
27530 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
27540 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
27550 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
27560 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
27570 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
27580 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
27590 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
275a0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
275b0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
275c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
275d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
275e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
275f0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
27600 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
27610 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
27620 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
27630 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
27640 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
27650 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
27660 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
27670 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
27680 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
27690 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
276a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
276b0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
276c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
276d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
276e0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
276f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27700 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
27710 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27720 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27730 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
27740 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
27750 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
27760 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
27770 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
27780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27790 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
277a0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
277b0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
277c0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
277d0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
277e0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
277f0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
27800 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
27810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27820 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
27830 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27840 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
27850 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
27860 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
27870 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
27880 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
27890 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
278a0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
278b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
278c0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
278d0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
278e0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
278f0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
27900 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
27910 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
27920 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
27930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27940 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
27950 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
27960 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
27970 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
27980 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
27990 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
279a0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
279b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
279c0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
279d0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
279e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
279f0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
27a00 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27a10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
27a20 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
27a30 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
27a40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
27a50 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
27a60 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
27a70 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
27a80 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
27a90 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
27aa0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
27ab0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27ac0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
27ad0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
27ae0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
27af0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
27b00 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
27b10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
27b20 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
27b30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
27b40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
27b50 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
27b60 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
27b70 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
27b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27b90 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
27ba0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
27bb0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
27bc0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
27bd0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
27be0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
27bf0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
27c00 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
27c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
27c20 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
27c30 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
27c40 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
27c50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27c60 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
27c70 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
27c80 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
27c90 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
27ca0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
27cb0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
27cc0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
27cd0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
27ce0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
27cf0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
27d00 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
27d10 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
27d20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
27d30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
27d40 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
27d50 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
27d60 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
27d70 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
27d80 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
27d90 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
27da0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
27db0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
27dc0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
27dd0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
27de0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
27df0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
27e00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
27e10 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
27e20 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
27e30 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
27e40 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
27e50 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
27e60 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
27e70 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
27e80 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
27e90 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
27ea0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
27eb0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
27ec0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
27ed0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
27ee0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
27ef0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
27f00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27f10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
27f20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27f30 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
27f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
27f50 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
27f60 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
27f70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
27f80 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
27f90 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
27fa0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
27fb0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
27fc0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
27fd0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
27fe0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
27ff0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
28000 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
28010 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
28020 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
28030 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
28040 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
28050 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
28060 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
28070 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
28080 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
28090 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
280a0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
280b0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
280c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
280d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
280e0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
280f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
28100 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
28110 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
28120 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
28130 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
28140 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
28150 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
28160 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
28170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28180 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
28190 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
281a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
281b0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
281c0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
281d0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
281e0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
281f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
28200 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
28210 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
28220 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
28230 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
28240 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
28250 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
28260 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
28270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
28280 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
28290 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
282a0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
282b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
282c0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
282d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
282e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
282f0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
28300 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
28310 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
28320 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
28330 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
28340 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
28350 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
28360 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
28370 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
28380 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
28390 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
283a0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
283b0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
283c0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
283d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
283e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
283f0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
28400 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
28410 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
28420 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
28430 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
28440 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
28450 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
28460 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
28470 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
28480 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
28490 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
284a0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
284b0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
284c0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
284d0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
284e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
284f0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
28500 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
28510 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
28520 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
28530 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
28540 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
28550 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
28560 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
28570 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
28580 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
28590 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
285a0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
285b0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
285c0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
285d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
285e0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
285f0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
28600 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
28610 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
28620 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
28630 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
28640 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
28650 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
28660 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
28670 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
28680 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
28690 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
286a0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
286b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
286c0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
286d0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
286e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
286f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28700 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
28710 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
28720 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
28730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
28740 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
28750 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
28760 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
28770 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
28780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
28790 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
287a0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
287b0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
287c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
287d0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
287e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
287f0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
28800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28810 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
28820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28830 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
28840 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28850 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
28860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
28870 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
28880 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28890 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
288a0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
288b0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
288c0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
288d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
288e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
288f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28900 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
28910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
28920 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
28930 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28950 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
28960 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
28970 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
28980 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
28990 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
289a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
289b0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
289c0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
289d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
289e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
289f0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
28a00 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
28a10 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
28a20 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
28a30 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
28a40 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
28a50 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
28a60 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
28a70 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
28a80 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
28a90 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
28aa0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
28ab0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
28ac0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
28ad0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
28ae0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
28af0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
28b00 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
28b10 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
28b20 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
28b30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
28b40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
28b50 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
28b60 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
28b70 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
28b80 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
28b90 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
28ba0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
28bb0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
28bc0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
28bd0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
28be0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
28bf0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
28c00 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
28c10 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
28c20 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
28c30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
28c40 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
28c50 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
28c60 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
28c70 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
28c80 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
28c90 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
28ca0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
28cb0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
28cc0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
28cd0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
28ce0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
28cf0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
28d00 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
28d10 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
28d20 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
28d30 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
28d40 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
28d50 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
28d60 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
28d70 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
28d80 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
28d90 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
28da0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
28db0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
28dc0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
28dd0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28de0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
28df0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
28e00 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
28e10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
28e20 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
28e30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28e40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28e50 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
28e60 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
28e70 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
28e80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28e90 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
28ea0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
28eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28ec0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28ed0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28ee0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
28ef0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
28f00 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
28f10 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
28f20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28f30 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
28f40 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
28f50 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
28f60 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
28f70 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
28f80 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
28f90 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
28fa0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
28fb0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
28fc0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
28fd0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
28fe0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
28ff0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
29000 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
29010 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
29020 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
29030 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
29040 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
29050 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
29060 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
29070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
29080 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
29090 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
290a0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
290b0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
290c0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
290d0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
290e0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
290f0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
29100 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
29110 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
29120 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
29130 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
29140 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
29150 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
29160 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
29170 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
29180 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
29190 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
291a0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
291b0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
291c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
291d0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
291e0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
291f0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
29200 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
29210 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
29220 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
29230 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
29240 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
29250 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
29260 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
29270 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
29280 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
29290 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
292a0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
292b0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
292c0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
292d0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
292e0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
292f0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
29300 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
29310 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
29320 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
29330 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
29340 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
29350 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
29360 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
29370 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
29380 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
29390 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
293a0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
293b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
293c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
293d0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
293e0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
293f0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
29400 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
29410 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
29420 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
29430 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
29440 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
29450 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
29460 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
29470 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
29480 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
29490 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
294a0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
294b0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
294c0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
294d0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
294e0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
294f0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
29500 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
29510 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
29520 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
29530 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
29540 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
29550 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
29560 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
29570 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
29580 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
29590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
295a0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
295b0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
295c0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
295d0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
295e0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
295f0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
29600 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
29610 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
29620 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
29630 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
29640 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
29650 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
29660 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
29670 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
29680 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
29690 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
296a0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
296b0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
296c0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
296d0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
296e0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
296f0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
29700 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
29710 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
29720 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
29730 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
29740 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
29750 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29760 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
29770 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29780 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
29790 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
297a0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
297b0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
297c0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
297d0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
297e0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
297f0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
29800 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
29810 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
29820 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
29830 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
29840 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
29850 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
29860 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
29870 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
29880 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
29890 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
298a0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
298b0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
298c0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
298d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
298e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
298f0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
29900 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
29910 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
29920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
29930 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
29940 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
29950 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
29960 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
29970 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
29980 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
29990 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
299a0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
299b0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
299c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
299d0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
299e0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
299f0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
29a00 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
29a10 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
29a20 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
29a30 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
29a40 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
29a50 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
29a60 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
29a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
29a80 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
29a90 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
29aa0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
29ab0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
29ac0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
29ad0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
29ae0 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
29af0 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
29b00 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
29b10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29b20 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
29b30 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
29b40 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
29b50 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
29b60 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
29b70 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
29b80 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
29b90 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
29ba0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
29bb0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
29bc0 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
29bd0 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
29be0 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
29bf0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
29c00 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
29c10 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
29c20 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
29c30 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
29c40 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
29c50 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
29c60 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
29c70 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
29c80 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
29c90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
29ca0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
29cb0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
29cc0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
29cd0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
29ce0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
29cf0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
29d00 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
29d10 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
29d20 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
29d30 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
29d40 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
29d50 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
29d60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29d70 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
29d80 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
29d90 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
29da0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
29db0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
29dc0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
29dd0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
29de0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
29df0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
29e00 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
29e10 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
29e20 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
29e30 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
29e40 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
29e50 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
29e60 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
29e70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29e80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29e90 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
29ea0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
29eb0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
29ec0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
29ed0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29ee0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
29ef0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
29f00 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
29f10 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
29f20 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
29f30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29f40 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
29f50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
29f60 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
29f70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
29f80 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
29f90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29fa0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
29fb0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
29fc0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
29fd0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
29fe0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
29ff0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2a000 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a010 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2a020 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2a030 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2a040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a050 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2a060 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2a070 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2a080 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2a090 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2a0a0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2a0b0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2a0c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2a0d0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2a0e0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2a0f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2a100 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2a110 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2a120 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2a130 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2a140 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2a150 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2a160 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a170 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2a180 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2a190 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2a1a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2a1b0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2a1c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2a1d0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2a1e0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2a1f0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2a200 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2a210 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2a220 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2a230 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2a240 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2a250 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2a260 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2a270 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2a280 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2a290 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2a2a0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2a2b0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2a2c0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2a2d0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2a2e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a2f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a300 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2a310 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a320 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2a330 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a340 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2a350 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2a360 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2a370 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2a380 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2a390 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2a3a0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2a3b0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2a3c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2a3d0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2a3e0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2a3f0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2a400 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2a410 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2a420 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2a430 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2a440 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2a450 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2a460 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2a470 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2a480 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2a490 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2a4a0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2a4b0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2a4c0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2a4d0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2a4e0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2a4f0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2a500 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2a510 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2a520 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2a530 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2a540 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2a550 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2a560 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2a570 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2a580 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2a590 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2a5a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2a5b0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2a5c0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2a5d0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2a5e0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2a5f0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2a600 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2a610 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2a620 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2a630 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2a640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a650 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2a660 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2a670 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2a680 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2a690 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a6a0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2a6b0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2a6c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2a6d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2a6e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2a6f0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2a700 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2a710 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2a720 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2a730 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2a740 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a750 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2a760 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2a770 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2a780 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2a790 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2a7a0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2a7b0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2a7c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2a7d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2a7e0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2a7f0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2a800 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2a810 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2a820 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2a830 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2a840 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2a850 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2a860 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2a870 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2a880 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2a890 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2a8a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2a8b0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2a8c0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2a8d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a8e0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2a8f0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2a900 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2a910 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2a920 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2a930 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2a940 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2a950 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2a960 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2a970 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2a980 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2a990 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2a9a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2a9b0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a9c0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2a9d0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2a9e0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2a9f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2aa00 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2aa10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2aa20 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2aa30 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2aa40 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2aa50 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2aa60 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2aa70 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2aa80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2aa90 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2aaa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2aab0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2aac0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2aad0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2aae0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2aaf0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2ab00 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2ab10 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2ab20 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2ab30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ab40 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2ab50 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2ab60 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2ab70 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2ab80 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2ab90 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2aba0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2abb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2abc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2abd0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2abe0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2abf0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2ac00 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2ac10 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2ac20 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2ac30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2ac40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2ac50 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2ac60 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2ac70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2ac80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2ac90 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2aca0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2acb0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2acc0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2acd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ace0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2acf0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2ad00 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2ad10 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2ad20 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2ad30 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2ad40 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2ad50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2ad60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ad70 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2ad80 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2ad90 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2ada0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2adb0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2adc0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2add0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2ade0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2adf0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2ae00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ae10 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2ae20 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2ae30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ae40 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2ae50 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2ae60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2ae70 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2ae80 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2ae90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2aea0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2aeb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2aec0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2aed0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2aee0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2aef0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2af00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2af10 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2af20 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2af30 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2af40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2af50 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2af60 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2af70 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2af80 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2af90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2afa0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2afb0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2afc0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2afd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2afe0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2aff0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2b000 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2b010 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b020 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2b030 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2b040 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2b050 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2b060 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2b070 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b080 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2b090 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2b0a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2b0b0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2b0c0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2b0d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b0e0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2b0f0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2b100 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2b110 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2b120 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2b130 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2b140 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2b150 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2b160 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2b170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2b180 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2b190 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2b1a0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2b1b0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2b1c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2b1d0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2b1e0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2b1f0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2b200 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2b210 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2b220 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2b230 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2b240 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2b250 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b260 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2b270 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b280 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2b290 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2b2a0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2b2b0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2b2c0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2b2d0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2b2e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2b2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b300 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2b310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b320 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2b330 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2b340 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2b350 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2b360 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2b370 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2b380 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b390 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2b3a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2b3b0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2b3c0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2b3d0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2b3e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2b3f0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2b400 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2b410 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2b420 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2b430 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2b440 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2b450 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2b460 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2b470 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2b480 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2b490 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b4a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2b4b0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2b4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b4d0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2b4e0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2b4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2b500 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b510 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2b520 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2b530 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b540 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2b550 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2b560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2b570 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2b580 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2b590 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
2b5a0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
2b5b0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
2b5c0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
2b5d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2b5e0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2b5f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2b600 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
2b610 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2b620 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
2b630 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
2b640 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2b650 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
2b660 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
2b670 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
2b680 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
2b690 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
2b6a0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
2b6b0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
2b6c0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
2b6d0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
2b6e0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
2b6f0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
2b700 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
2b710 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
2b720 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2b730 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2b740 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2b750 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2b760 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2b770 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2b780 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2b790 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2b7a0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2b7b0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2b7c0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2b7d0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b7e0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b7f0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b800 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2b810 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2b820 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2b830 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2b840 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b850 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2b860 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b870 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b880 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b890 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b8a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b8b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b8c0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2b8d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b8e0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b8f0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2b900 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2b910 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2b920 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b930 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b940 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b950 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2b960 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b970 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2b980 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2b990 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2b9a0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b9b0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
2b9c0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
2b9d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b9e0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
2b9f0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2ba00 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
2ba10 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2ba20 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2ba30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2ba40 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
2ba50 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
2ba60 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2ba70 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
2ba80 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2ba90 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2baa0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
2bab0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2bac0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2bad0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2bae0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2baf0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2bb00 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2bb10 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2bb20 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2bb30 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2bb40 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2bb50 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2bb60 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2bb70 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
2bb80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2bb90 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2bba0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2bbb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2bbc0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2bbd0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2bbe0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2bbf0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2bc00 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2bc10 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2bc20 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2bc30 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2bc40 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2bc50 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2bc60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2bc70 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2bc80 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2bc90 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2bca0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2bcb0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2bcc0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2bcd0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2bce0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2bcf0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2bd00 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2bd10 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2bd20 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2bd30 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2bd40 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2bd50 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2bd60 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2bd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2bd80 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2bd90 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2bda0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2bdb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2bdc0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2bdd0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2bde0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2bdf0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2be00 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2be10 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2be20 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2be30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2be40 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2be50 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2be60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2be70 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2be80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2be90 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2bea0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2beb0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2bec0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2bed0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2bee0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2bef0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2bf00 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2bf10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2bf20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2bf30 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2bf40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bf50 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2bf60 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2bf70 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2bf80 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2bf90 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2bfa0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2bfb0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2bfc0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bfd0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2bfe0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2bff0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2c000 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2c010 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2c020 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2c030 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2c040 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2c050 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2c060 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2c070 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2c080 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2c090 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2c0a0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2c0b0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2c0c0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2c0d0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2c0e0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2c0f0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2c100 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2c110 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2c120 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2c130 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2c140 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2c150 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2c160 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2c170 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2c180 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2c190 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2c1a0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2c1b0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2c1c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2c1d0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2c1e0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2c1f0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2c200 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2c210 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2c220 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2c230 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2c240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c250 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2c260 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2c270 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2c280 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2c290 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2c2a0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2c2b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2c2c0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2c2d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c2e0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2c2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c300 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2c310 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2c320 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2c330 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2c340 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c350 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2c360 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2c370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c380 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2c390 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2c3a0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2c3b0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2c3c0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2c3d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c3e0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2c3f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c400 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2c410 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2c420 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2c430 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2c440 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2c450 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c460 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2c470 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2c480 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c490 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2c4a0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2c4b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c4c0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2c4d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2c4e0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2c4f0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2c500 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2c510 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2c520 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2c530 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2c540 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2c550 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2c560 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2c570 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2c580 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c590 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2c5a0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2c5b0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2c5c0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2c5d0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2c5e0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2c5f0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2c600 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2c610 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
2c620 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2c630 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c640 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2c650 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2c660 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2c670 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
2c680 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2c690 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2c6a0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2c6b0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2c6c0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2c6d0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2c6e0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2c6f0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2c700 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2c710 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2c720 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2c730 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2c740 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2c750 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2c760 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2c770 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2c780 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2c790 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
2c7a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c7b0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2c7c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c7d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2c7e0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2c7f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c810 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2c820 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c830 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2c840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2c850 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2c860 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2c870 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2c880 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2c890 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c8a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2c8b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2c8c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2c8d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2c8e0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2c8f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c900 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2c910 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c920 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c940 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c950 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2c960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c970 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2c980 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2c990 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2c9a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2c9b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c9c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2c9d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2c9e0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2c9f0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2ca00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ca10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2ca20 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2ca30 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2ca40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ca50 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
2ca60 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2ca70 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
2ca80 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
2ca90 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
2caa0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
2cab0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
2cac0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
2cad0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
2cae0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
2caf0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
2cb00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2cb10 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
2cb20 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
2cb30 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
2cb40 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
2cb50 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
2cb60 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2cb70 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
2cb80 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
2cb90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2cba0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2cbb0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2cbc0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2cbd0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
2cbe0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
2cbf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc00 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
2cc10 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
2cc20 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
2cc30 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
2cc40 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
2cc50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
2cc60 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
2cc70 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
2cc80 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
2cc90 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2cca0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
2ccb0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
2ccc0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
2ccd0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
2cce0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ccf0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
2cd00 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
2cd10 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
2cd20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2cd30 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
2cd40 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
2cd50 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
2cd60 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
2cd70 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
2cd80 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
2cd90 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
2cda0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
2cdb0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
2cdc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2cdd0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2cde0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
2cdf0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
2ce00 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2ce10 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2ce20 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
2ce30 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
2ce40 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
2ce50 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
2ce60 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
2ce70 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
2ce80 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
2ce90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ceb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2cec0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2ced0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2cee0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2cef0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2cf00 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2cf10 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2cf20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cf30 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2cf40 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2cf50 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2cf60 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2cf70 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2cf80 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2cf90 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2cfa0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2cfb0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2cfc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2cfd0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2cfe0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2cff0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2d000 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2d010 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2d020 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2d030 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2d040 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2d050 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2d060 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2d070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d080 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2d090 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2d0a0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2d0b0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2d0c0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d0d0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d0e0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2d0f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d100 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2d110 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2d120 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2d130 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2d140 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2d150 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2d160 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2d170 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2d180 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2d190 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2d1a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2d1b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d1c0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2d1d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d1e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2d1f0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2d200 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2d210 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2d220 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2d230 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2d240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2d250 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2d260 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2d270 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2d280 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2d290 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d2a0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2d2b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d2c0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2d2d0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2d2e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d2f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2d300 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2d310 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2d320 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2d330 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2d340 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2d350 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2d360 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d370 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2d380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2d390 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d3a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2d3b0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2d3c0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2d3d0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2d3e0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2d3f0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2d400 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2d410 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2d420 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2d430 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2d440 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2d450 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2d460 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2d470 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2d480 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2d490 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2d4a0 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2d4b0 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2d4c0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
2d4d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2d4e0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
2d4f0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2d500 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
2d510 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
2d520 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
2d530 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2d540 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
2d550 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2d560 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2d570 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d580 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2d590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2d5a0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2d5b0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2d5c0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
2d5d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
2d5e0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2d5f0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2d600 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
2d610 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d620 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2d630 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
2d640 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
2d650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
2d660 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2d670 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2d680 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2d690 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2d6a0 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
2d6b0 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
2d6c0 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
2d6d0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2d6e0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2d6f0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
2d700 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
2d710 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
2d720 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2d730 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
2d740 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
2d750 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2d760 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
2d770 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
2d780 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
2d790 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
2d7a0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2d7b0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2d7c0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2d7d0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2d7e0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
2d7f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2d800 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
2d810 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2d820 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d830 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2d840 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2d850 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2d860 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
2d870 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
2d880 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2d890 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2d8a0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2d8b0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2d8c0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
2d8d0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
2d8e0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
2d8f0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2d900 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2d910 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
2d920 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
2d930 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
2d940 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2d950 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
2d960 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
2d970 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d980 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
2d990 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2d9a0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2d9b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2d9c0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2d9d0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2d9e0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2d9f0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2da00 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
2da10 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2da20 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
2da30 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
2da40 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2da50 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2da60 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2da70 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2da80 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2da90 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2daa0 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2dab0 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
2dac0 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
2dad0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2dae0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2daf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2db00 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2db10 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2db20 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2db30 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2db40 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2db50 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
2db60 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
2db70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2db80 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2db90 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
2dba0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2dbb0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
2dbc0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
2dbd0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2dbe0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
2dbf0 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
2dc00 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
2dc10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
2dc20 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
2dc30 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
2dc40 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
2dc50 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
2dc60 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
2dc70 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
2dc80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
2dc90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2dca0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2dcb0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2dcc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2dcd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2dce0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2dcf0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2dd00 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2dd10 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
2dd20 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
2dd30 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
2dd40 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2dd50 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2dd60 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2dd70 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2dd80 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2dd90 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2dda0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2ddb0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
2ddc0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2ddd0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2dde0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ddf0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2de00 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
2de10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
2de20 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2de30 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2de40 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2de50 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
2de60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2de70 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2de80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2de90 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2dea0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
2deb0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2dec0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
2ded0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2dee0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2def0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2df00 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
2df10 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
2df20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
2df30 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
2df40 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
2df50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2df60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2df70 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
2df80 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
2df90 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
2dfa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2dfb0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
2dfc0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
2dfd0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
2dfe0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
2dff0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
2e000 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
2e010 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
2e020 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2e030 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
2e040 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
2e050 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
2e060 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
2e070 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2e080 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2e090 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
2e0a0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
2e0b0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
2e0c0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
2e0d0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
2e0e0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
2e0f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2e100 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
2e110 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
2e120 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
2e130 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
2e140 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
2e150 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2e160 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2e170 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
2e180 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2e190 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2e1a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e1b0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2e1c0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2e1d0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2e1e0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2e1f0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2e200 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2e210 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2e220 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e230 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
2e240 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
2e250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
2e260 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
2e270 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2e280 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2e290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2e2a0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
2e2b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2e2c0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
2e2d0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
2e2e0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
2e2f0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
2e300 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e310 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
2e320 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
2e330 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
2e340 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
2e350 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2e360 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
2e370 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2e380 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
2e390 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2e3a0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e3b0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2e3c0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
2e3d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2e3e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2e3f0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
2e400 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
2e410 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
2e420 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
2e430 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2e440 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e450 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
2e460 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
2e470 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
2e480 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
2e490 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
2e4a0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
2e4b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e4c0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
2e4d0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
2e4e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2e4f0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2e500 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
2e510 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
2e520 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
2e530 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
2e540 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
2e550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e560 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
2e570 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2e580 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2e590 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
2e5a0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2e5b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e5c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e5d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e5e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e5f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2e600 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2e610 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2e620 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2e630 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2e640 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2e650 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2e660 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2e670 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e680 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e690 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e6a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2e6b0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2e6c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e6d0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
2e6e0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2e6f0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
2e700 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2e710 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2e720 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2e730 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2e740 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e750 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2e760 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2e770 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2e780 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2e790 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2e7a0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2e7b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e7c0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2e7d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e7e0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2e7f0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2e800 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2e810 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e820 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e830 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e840 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e850 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e870 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e880 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e890 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e8a0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e8b0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e8c0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
2e8d0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2e8e0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2e8f0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2e900 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
2e910 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2e920 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2e930 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2e940 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2e950 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2e960 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2e970 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2e980 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2e990 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2e9a0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2e9b0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2e9c0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2e9d0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2e9e0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2e9f0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2ea00 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2ea10 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2ea20 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2ea30 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2ea40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ea50 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2ea60 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2ea70 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2ea80 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2ea90 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2eaa0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2eab0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
2eac0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
2ead0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
2eae0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2eaf0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
2eb00 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
2eb10 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
2eb20 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2eb30 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
2eb40 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
2eb50 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
2eb60 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
2eb70 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
2eb80 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2eb90 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2eba0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2ebb0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2ebc0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2ebd0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2ebe0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2ebf0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2ec00 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2ec10 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
2ec20 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
2ec30 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
2ec40 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2ec50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
2ec60 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2ec70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2ec80 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2ec90 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2eca0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2ecb0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
2ecc0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2ecd0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
2ece0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2ecf0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
2ed00 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2ed10 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2ed20 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
2ed30 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
2ed40 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
2ed50 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2ed60 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2ed70 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2ed80 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
2ed90 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
2eda0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2edb0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
2edc0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2edd0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
2ede0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2edf0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
2ee00 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
2ee10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
2ee20 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
2ee30 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
2ee40 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2ee50 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
2ee60 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
2ee70 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
2ee80 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
2ee90 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
2eea0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
2eeb0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
2eec0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
2eed0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
2eee0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
2eef0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
2ef00 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
2ef10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ef20 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2ef30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ef40 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2ef50 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
2ef60 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2ef70 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2ef80 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2ef90 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
2efa0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
2efb0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
2efc0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
2efd0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
2efe0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2eff0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
2f000 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
2f010 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2f020 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
2f030 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
2f040 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
2f050 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2f060 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
2f070 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
2f080 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f090 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
2f0a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f0b0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
2f0c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f0d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2f0e0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
2f0f0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
2f100 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
2f110 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f120 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
2f130 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
2f140 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
2f150 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2f160 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2f170 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2f180 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2f190 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2f1a0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2f1b0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2f1c0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2f1d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2f1e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2f1f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2f200 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2f210 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2f220 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2f230 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2f240 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f250 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2f260 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
2f270 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
2f280 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
2f290 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
2f2a0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
2f2b0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
2f2c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f2d0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
2f2e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f2f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2f300 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
2f310 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
2f320 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
2f330 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
2f340 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
2f350 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2f360 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
2f370 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2f380 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
2f390 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
2f3a0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
2f3b0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
2f3c0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
2f3d0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
2f3e0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
2f3f0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
2f400 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
2f410 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
2f420 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
2f430 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
2f440 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
2f450 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
2f460 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
2f470 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
2f480 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
2f490 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
2f4a0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
2f4b0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
2f4c0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
2f4d0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
2f4e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2f4f0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2f500 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2f510 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
2f520 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
2f530 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
2f540 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
2f550 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
2f560 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2f570 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2f580 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2f590 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
2f5a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
2f5b0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
2f5c0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
2f5d0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
2f5e0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2f5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2f600 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
2f610 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
2f620 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f630 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2f640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f650 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
2f660 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2f670 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2f680 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2f690 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
2f6a0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
2f6b0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
2f6c0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
2f6d0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
2f6e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2f6f0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
2f700 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f710 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2f720 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
2f730 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2f740 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
2f750 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
2f760 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
2f770 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
2f780 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2f790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2f7a0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2f7b0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2f7c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2f7d0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
2f7e0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
2f7f0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2f800 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
2f810 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2f820 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f830 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2f840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f850 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f860 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f870 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
2f880 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2f890 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2f8a0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2f8b0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f8c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2f8d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f8e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2f8f0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2f900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f920 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
2f930 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
2f940 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
2f950 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
2f960 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2f970 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
2f980 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
2f990 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
2f9a0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
2f9b0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
2f9c0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
2f9d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f9e0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
2f9f0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
2fa00 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
2fa10 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
2fa20 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
2fa30 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
2fa40 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
2fa50 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
2fa60 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
2fa70 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2fa80 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
2fa90 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2faa0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2fab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2fac0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2fad0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2fae0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2faf0 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
2fb00 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
2fb10 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
2fb20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2fb30 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
2fb40 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
2fb50 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
2fb60 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
2fb70 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
2fb80 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
2fb90 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
2fba0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
2fbb0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
2fbc0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
2fbd0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
2fbe0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
2fbf0 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
2fc00 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2fc10 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
2fc20 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
2fc30 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
2fc40 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
2fc50 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
2fc60 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
2fc70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2fc80 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
2fc90 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
2fca0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
2fcb0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
2fcc0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
2fcd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
2fce0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2fcf0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
2fd00 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2fd10 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
2fd20 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
2fd30 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
2fd40 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2fd50 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
2fd60 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
2fd70 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
2fd80 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
2fd90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2fda0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
2fdb0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2fdc0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
2fdd0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
2fde0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
2fdf0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
2fe00 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
2fe10 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2fe20 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fe30 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
2fe40 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
2fe50 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
2fe60 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
2fe70 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
2fe80 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
2fe90 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
2fea0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
2feb0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
2fec0 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
2fed0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2fee0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
2fef0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
2ff00 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
2ff10 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2ff20 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
2ff30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2ff40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2ff50 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2ff60 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2ff70 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2ff80 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
2ff90 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
2ffa0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2ffb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2ffc0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
2ffd0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2ffe0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
2fff0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
30000 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
30010 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
30020 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
30030 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
30040 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
30050 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30060 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
30070 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
30080 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
30090 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
300a0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
300b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
300c0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
300d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
300e0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
300f0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
30100 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
30110 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
30120 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
30130 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
30140 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30150 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
30160 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30170 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
30180 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
30190 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
301a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
301b0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
301c0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
301d0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
301e0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
301f0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
30200 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
30210 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30220 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
30230 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
30240 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
30250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
30260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30270 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
30280 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
30290 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
302a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
302b0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
302c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
302d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
302e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
302f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30300 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
30310 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
30320 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30330 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
30340 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
30350 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
30360 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
30370 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
30380 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
30390 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
303a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
303b0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
303c0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
303d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
303e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
303f0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
30400 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
30410 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
30420 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
30430 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
30440 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
30450 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
30460 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
30470 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
30480 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
30490 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
304a0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
304b0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
304c0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
304d0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
304e0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
304f0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
30500 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
30510 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
30520 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
30530 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
30540 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
30550 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
30560 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
30570 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
30580 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
30590 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
305a0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
305b0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
305c0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
305d0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
305e0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
305f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
30600 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
30610 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
30620 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
30630 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
30640 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
30650 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
30660 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
30670 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
30680 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
30690 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
306a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
306b0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
306c0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
306d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
306e0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
306f0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
30700 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
30710 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
30720 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
30730 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
30740 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
30750 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
30760 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
30770 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
30780 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30790 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
307a0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
307b0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
307c0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
307d0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
307e0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
307f0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
30800 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
30810 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
30820 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
30830 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
30840 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
30850 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
30860 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
30870 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
30880 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
30890 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
308a0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
308b0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
308c0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
308d0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
308e0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
308f0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
30900 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
30910 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30920 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
30930 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
30940 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
30950 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
30960 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
30970 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
30980 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
30990 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
309a0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
309b0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
309c0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
309d0 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
309e0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
309f0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
30a00 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
30a10 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
30a20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
30a30 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
30a40 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
30a50 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
30a60 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
30a70 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
30a80 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
30a90 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
30aa0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
30ab0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
30ac0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
30ad0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
30ae0 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
30af0 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
30b00 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
30b10 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
30b20 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
30b30 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
30b40 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
30b50 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
30b60 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
30b70 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
30b80 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
30b90 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
30ba0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
30bb0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
30bc0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
30bd0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
30be0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
30bf0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
30c00 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
30c10 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
30c20 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30c30 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30c40 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
30c50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
30c60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
30c70 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
30c80 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
30c90 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
30ca0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
30cb0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
30cc0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
30cd0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
30ce0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
30cf0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
30d00 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
30d10 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
30d20 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
30d30 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
30d40 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
30d50 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
30d60 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
30d70 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
30d80 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
30d90 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
30da0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
30db0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
30dc0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
30dd0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
30de0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
30df0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
30e00 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
30e10 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
30e20 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
30e30 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
30e40 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
30e50 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
30e60 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
30e70 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
30e80 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
30e90 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
30ea0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
30eb0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
30ec0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
30ed0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
30ee0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
30ef0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
30f00 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
30f10 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
30f20 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
30f30 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
30f40 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
30f50 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
30f60 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
30f70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
30f80 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
30f90 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
30fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
30fb0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
30fc0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
30fd0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
30fe0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
30ff0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
31000 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
31010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
31020 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
31030 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
31040 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
31050 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
31060 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
31070 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
31080 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
31090 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
310a0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
310b0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
310c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
310d0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
310e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
310f0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
31100 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
31110 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
31120 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
31130 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
31140 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
31150 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
31160 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
31170 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
31180 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
31190 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
311a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
311b0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
311c0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
311d0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
311e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
311f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
31200 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31210 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
31220 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31230 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
31240 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31250 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
31260 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
31270 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
31280 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
31290 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
312a0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
312b0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
312c0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
312d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
312e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
312f0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
31300 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
31310 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
31320 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
31330 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31340 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
31350 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
31360 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
31370 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
31380 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
31390 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
313a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
313b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
313c0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
313d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
313e0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
313f0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
31400 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31410 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
31420 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
31430 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
31440 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
31450 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
31460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31470 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
31480 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31490 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
314a0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
314b0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
314c0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
314d0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
314e0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
314f0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
31500 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
31510 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
31520 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31530 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
31540 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
31550 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
31560 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
31570 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
31580 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
31590 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
315a0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
315b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
315c0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
315d0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
315e0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
315f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31600 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
31610 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
31620 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
31630 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
31640 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
31650 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
31660 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31670 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
31680 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31690 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
316a0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
316b0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
316c0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
316d0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
316e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
316f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
31700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31710 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
31720 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31730 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
31740 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
31750 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
31760 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
31770 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
31780 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31790 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
317a0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
317b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
317c0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
317d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
317e0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
317f0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
31800 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
31810 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
31820 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
31830 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
31840 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
31850 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
31860 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
31870 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
31880 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
31890 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
318a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
318b0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
318c0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
318d0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
318e0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
318f0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
31900 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
31910 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
31920 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
31930 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
31940 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
31950 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
31960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31970 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
31980 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31990 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
319a0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
319b0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
319c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
319d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
319e0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
319f0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
31a00 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
31a10 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
31a20 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
31a30 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
31a40 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
31a50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31a60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
31a70 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
31a80 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
31a90 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
31aa0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
31ab0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
31ac0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
31ad0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31ae0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
31af0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31b00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31b10 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31b20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31b30 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
31b40 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
31b50 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
31b60 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
31b70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
31b80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31b90 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
31ba0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
31bb0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
31bc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31bd0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31be0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
31bf0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31c00 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
31c10 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
31c20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
31c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
31c40 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
31c50 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
31c60 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
31c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31c90 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
31ca0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31cb0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
31cc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
31cd0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
31ce0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
31cf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
31d00 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
31d10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
31d20 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
31d30 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
31d40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31d50 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
31d60 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
31d70 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
31d80 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
31d90 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
31da0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
31db0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
31dc0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
31dd0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
31de0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
31df0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
31e00 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
31e10 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
31e20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31e30 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
31e40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31e50 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
31e60 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
31e70 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31e80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31e90 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31ea0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
31eb0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
31ec0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
31ed0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
31ee0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
31ef0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
31f00 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
31f10 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31f20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31f30 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31f40 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
31f50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
31f60 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
31f70 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
31f80 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
31f90 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
31fa0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
31fb0 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
31fc0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31fd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
31fe0 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
31ff0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
32000 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
32010 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
32020 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
32030 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
32040 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
32050 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
32060 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
32070 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
32080 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
32090 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
320a0 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
320b0 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
320c0 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
320d0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
320e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
320f0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
32100 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
32110 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
32120 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
32130 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
32140 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
32150 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
32160 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
32170 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
32180 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
32190 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
321a0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
321b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
321c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
321d0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
321e0 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
321f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
32200 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
32210 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
32220 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
32230 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
32240 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
32250 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
32260 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
32270 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
32280 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
32290 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
322a0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
322b0 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
322c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
322d0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
322e0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
322f0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
32300 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
32310 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
32320 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
32330 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
32340 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
32350 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
32360 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
32370 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
32380 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
32390 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
323a0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
323b0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
323c0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
323d0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
323e0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
323f0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
32400 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
32410 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32420 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
32430 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
32440 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
32450 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
32460 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
32470 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
32480 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
32490 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
324a0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
324b0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
324c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
324d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
324e0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
324f0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
32500 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32510 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32520 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
32530 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
32540 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32550 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
32560 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
32570 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
32580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
32590 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
325a0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
325b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
325c0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
325d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
325e0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
325f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
32600 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
32610 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
32620 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
32630 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
32640 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
32650 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
32660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32670 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
32680 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
32690 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
326a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
326b0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
326c0 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
326d0 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
326e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
326f0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
32700 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
32710 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
32720 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
32730 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
32740 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
32750 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
32760 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
32770 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
32780 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32790 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
327a0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
327b0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
327c0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
327d0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
327e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
327f0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
32800 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32810 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
32820 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
32830 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32840 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
32850 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
32860 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
32870 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
32880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32890 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
328a0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
328b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
328c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
328d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
328e0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
328f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
32900 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
32910 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
32920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32930 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
32940 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
32950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32960 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
32970 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32980 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32990 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
329a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
329b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
329c0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
329d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
329e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
329f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32a00 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
32a10 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
32a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32a30 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
32a40 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
32a50 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32a60 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32a70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32a80 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
32a90 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32aa0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32ab0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32ad0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
32ae0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32af0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
32b00 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32b10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32b20 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
32b30 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32b40 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
32b50 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
32b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32b70 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
32b80 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
32b90 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
32ba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
32bb0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
32bc0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
32bd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32be0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
32bf0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
32c00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
32c10 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
32c20 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
32c30 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
32c40 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
32c50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
32c60 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
32c70 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
32c80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
32c90 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
32ca0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
32cb0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
32cc0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32cd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
32ce0 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
32cf0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
32d00 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
32d10 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
32d20 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
32d30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32d40 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
32d50 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
32d60 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
32d70 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
32d80 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
32d90 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
32da0 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
32db0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
32dc0 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
32dd0 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
32de0 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
32df0 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
32e00 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
32e10 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
32e20 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32e30 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
32e40 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
32e50 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
32e60 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
32e70 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
32e80 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
32e90 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
32ea0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
32eb0 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
32ec0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
32ed0 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
32ee0 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
32ef0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
32f00 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
32f10 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
32f20 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
32f30 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
32f40 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
32f50 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
32f60 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
32f70 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
32f80 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
32f90 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
32fa0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
32fb0 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
32fc0 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
32fd0 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
32fe0 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
32ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
33000 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
33010 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
33020 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
33030 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
33040 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
33050 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
33060 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
33070 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
33080 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
33090 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
330a0 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
330b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
330c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
330d0 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
330e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
330f0 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
33100 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
33110 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
33120 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
33130 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
33140 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
33150 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
33160 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
33170 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
33180 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
33190 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
331a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
331b0 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
331c0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
331d0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
331e0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
331f0 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
33200 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33210 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
33220 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
33230 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
33240 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
33250 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
33260 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
33270 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
33280 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
33290 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
332a0 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
332b0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
332c0 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
332d0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
332e0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
332f0 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
33300 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
33310 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33320 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
33330 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
33340 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
33350 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
33360 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
33370 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
33380 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
33390 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
333a0 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
333b0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
333c0 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
333d0 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
333e0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
333f0 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
33400 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
33410 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
33420 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
33430 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
33440 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
33450 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
33460 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
33470 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
33480 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
33490 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
334a0 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
334b0 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
334c0 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
334d0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
334e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
334f0 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
33500 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
33510 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
33520 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
33530 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
33540 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
33550 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
33560 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
33570 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
33580 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
33590 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
335a0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
335b0 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
335c0 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
335d0 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
335e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
335f0 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
33600 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
33610 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
33620 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33630 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
33640 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
33650 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
33660 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
33670 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
33680 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33690 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
336a0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
336b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
336c0 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
336d0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
336e0 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
336f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
33700 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
33710 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33720 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
33730 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
33740 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
33750 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
33760 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
33770 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
33780 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
33790 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
337a0 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
337b0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
337c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
337d0 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
337e0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
337f0 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
33800 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
33810 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
33820 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
33830 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33840 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
33850 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
33860 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
33870 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
33880 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33890 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
338a0 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
338b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
338c0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
338d0 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
338e0 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
338f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
33900 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
33910 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
33920 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
33930 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
33940 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
33950 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
33960 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
33970 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
33980 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
33990 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
339a0 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
339b0 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
339c0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
339d0 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
339e0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
339f0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
33a00 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33a10 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
33a20 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33a30 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
33a40 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33a50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
33a60 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
33a70 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
33a80 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
33a90 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
33aa0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
33ab0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33ac0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33ad0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
33ae0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33af0 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
33b00 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
33b10 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
33b20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
33b30 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
33b40 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
33b50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33b60 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33b70 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
33b80 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33b90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
33ba0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
33bb0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33bc0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
33bd0 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
33be0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
33bf0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
33c00 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33c10 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
33c20 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
33c30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
33c40 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
33c50 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
33c60 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
33c70 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
33c80 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
33c90 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
33ca0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
33cb0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
33cc0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
33cd0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
33ce0 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
33cf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33d00 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
33d10 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
33d20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
33d30 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
33d40 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
33d50 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
33d60 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
33d70 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
33d80 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33d90 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
33da0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
33db0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
33dc0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
33dd0 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
33de0 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
33df0 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
33e00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33e10 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
33e20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
33e30 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
33e40 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
33e50 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
33e60 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
33e70 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
33e80 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
33e90 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
33ea0 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
33eb0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
33ec0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
33ed0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
33ee0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
33ef0 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
33f00 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
33f10 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
33f20 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33f30 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
33f40 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33f50 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
33f60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
33f70 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
33f80 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
33f90 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
33fa0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
33fb0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
33fc0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
33fd0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
33fe0 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
33ff0 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
34000 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
34010 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
34020 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
34030 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
34040 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
34050 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
34060 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
34070 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34080 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
34090 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
340a0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
340b0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
340c0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
340d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
340e0 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
340f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34100 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
34110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34120 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34130 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
34140 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34150 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
34160 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
34170 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34180 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
34190 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
341a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
341b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
341c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
341d0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
341e0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
341f0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
34200 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
34210 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
34220 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
34230 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
34240 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
34250 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
34260 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
34270 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
34280 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
34290 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
342a0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
342b0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
342c0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
342d0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
342e0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
342f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
34300 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
34310 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
34320 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
34330 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
34340 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
34350 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
34360 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
34370 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
34380 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
34390 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
343a0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
343b0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
343c0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
343d0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
343e0 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
343f0 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
34400 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
34410 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
34420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
34430 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
34440 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
34450 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
34460 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
34470 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
34480 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
34490 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
344a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
344b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
344c0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
344d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
344e0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
344f0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
34500 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
34510 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
34520 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
34530 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
34540 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
34550 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
34560 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
34570 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
34580 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
34590 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
345a0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
345b0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
345c0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
345d0 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
345e0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
345f0 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
34600 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
34610 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
34620 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
34630 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
34640 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
34650 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
34660 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
34670 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
34680 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
34690 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
346a0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
346b0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
346c0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
346d0 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
346e0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
346f0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
34700 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34710 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
34720 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
34730 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
34740 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
34750 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
34760 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
34770 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
34780 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
34790 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
347a0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
347b0 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
347c0 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
347d0 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
347e0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
347f0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
34800 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
34810 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
34820 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
34830 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
34840 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
34850 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
34860 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
34870 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
34880 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
34890 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
348a0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
348b0 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
348c0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
348d0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
348e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
348f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
34900 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
34910 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
34920 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
34930 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
34940 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
34950 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
34960 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
34970 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
34980 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
34990 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
349a0 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
349b0 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
349c0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
349d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
349e0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
349f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
34a00 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
34a10 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
34a20 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
34a30 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
34a40 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
34a50 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
34a60 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
34a70 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
34a80 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
34a90 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
34aa0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
34ab0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
34ac0 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
34ad0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
34ae0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
34af0 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
34b00 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
34b10 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
34b20 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
34b30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
34b40 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
34b50 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
34b60 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
34b70 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
34b80 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
34b90 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
34ba0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
34bb0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
34bc0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
34bd0 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
34be0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
34bf0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
34c00 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
34c10 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
34c20 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
34c30 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
34c40 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
34c50 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
34c60 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
34c70 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
34c80 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
34c90 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
34ca0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
34cb0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
34cc0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
34cd0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
34ce0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
34cf0 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
34d00 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
34d10 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
34d20 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
34d30 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
34d40 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
34d50 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
34d60 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
34d70 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
34d80 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
34d90 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
34da0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
34db0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
34dc0 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
34dd0 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
34de0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
34df0 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
34e00 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
34e10 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
34e20 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
34e30 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
34e40 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
34e50 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
34e60 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
34e70 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
34e80 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
34e90 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
34ea0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
34eb0 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
34ec0 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
34ed0 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
34ee0 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
34ef0 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
34f00 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
34f10 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
34f20 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
34f30 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
34f40 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
34f50 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
34f60 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
34f70 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
34f80 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  voided..**.** <b
34f90 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
34fa0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
34fb0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
34fc0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
34fd0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
34fe0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71  r to calling [sq
34ff0 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b  lite3_open] or [
35000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d  sqlite3_open_v2]
35010 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
35020 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
35030 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
35040 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
35050 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
35060 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a  il.  Here is an.
35070 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f  ** example of ho
35080 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69  w to do this usi
35090 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20  ng C++ with the 
350a0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a  Windows Runtime:
350b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
350c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57  te><pre>.** LPCW
350d0 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64  STR zPath = Wind
350e0 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70  ows::Storage::Ap
350f0 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43  plicationData::C
35100 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 20 20 20 20  urrent->.**     
35110 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d  TemporaryFolder-
35120 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a  >Path->Data();.*
35130 2a 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42  *.** char zPathB
35140 75 66 5b 4d 41 58 5f 50 41 54 48 20 2b 20 31 5d  uf[MAX_PATH + 1]
35150 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74  ;.** memset(zPat
35160 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28  hBuf, 0, sizeof(
35170 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 0a 2a  zPathBuf));.**.*
35180 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74  * WideCharToMult
35190 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30  iByte(CP_UTF8, 0
351a0 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61  , zPath, -1, zPa
351b0 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50  thBuf, sizeof(zP
351c0 61 74 68 42 75 66 29 2c 0a 2a 2a 20 20 20 20 20  athBuf),.**     
351d0 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 0a  NULL, NULL);.**.
351e0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
351f0 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
35200 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
35210 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
35220 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
35230 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
35240 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
35250 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
35260 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
35270 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
35280 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
35290 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
352a0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
352b0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
352c0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
352d0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
352e0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
352f0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
35300 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
35310 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
35320 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
35330 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
35340 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
35350 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
35360 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
35370 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
35380 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
35390 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
353a0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
353b0 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
353c0 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
353d0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
353e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
353f0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
35400 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
35410 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
35420 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
35430 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
35440 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
35450 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
35460 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
35470 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
35480 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
35490 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
354a0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
354b0 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
354c0 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
354d0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
354e0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
354f0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
35500 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
35510 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
35520 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35530 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
35540 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
35550 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
35560 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
35570 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
35580 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
35590 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
355a0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
355b0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
355c0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
355d0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
355e0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
355f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35600 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
35610 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
35620 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
35630 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
35640 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
35650 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
35660 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
35670 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
35680 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
35690 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
356a0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
356b0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
356c0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
356d0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
356e0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
356f0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
35700 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
35710 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
35720 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
35730 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
35740 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
35750 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
35760 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
35770 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
35780 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
35790 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
357a0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
357b0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
357c0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
357d0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
357e0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
357f0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
35800 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
35810 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
35820 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
35830 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
35840 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
35850 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
35860 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
35870 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
35880 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
35890 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
358a0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
358b0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
358c0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
358d0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
358e0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
358f0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
35900 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
35910 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
35920 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
35930 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
35940 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
35950 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
35960 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
35970 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f  te3_data_directo
35980 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
35990 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
359a0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
359b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
359c0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
359d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
359e0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
359f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35a00 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
35a10 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
35a20 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
35a30 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
35a40 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
35a50 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
35a60 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
35a70 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35a80 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
35a90 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
35aa0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
35ab0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
35ac0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
35ad0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
35ae0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
35af0 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
35b00 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
35b10 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
35b20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
35b30 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
35b40 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
35b50 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
35b60 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
35b70 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
35b80 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
35b90 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
35ba0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
35bb0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
35bc0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
35bd0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
35be0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
35bf0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
35c00 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
35c10 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
35c20 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
35c30 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
35c40 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
35c50 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
35c60 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
35c70 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
35c80 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
35c90 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
35ca0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
35cb0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
35cc0 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
35cd0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
35ce0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
35cf0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
35d00 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
35d10 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
35d20 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
35d30 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
35d40 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
35d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35d60 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
35d70 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
35d80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
35d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35da0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
35db0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35dc0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35dd0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
35de0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
35df0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35e00 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
35e10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35e20 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
35e30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
35e40 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
35e50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
35e60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
35e70 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
35e80 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
35e90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
35ea0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
35eb0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
35ec0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
35ed0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
35ee0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
35ef0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
35f00 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
35f10 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
35f20 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
35f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
35f40 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61  eturn The Filena
35f50 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73  me For A Databas
35f60 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
35f70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35f80 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29  db_filename(D,N)
35f90 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35fa0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
35fb0 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73  a filename.** as
35fc0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61  sociated with da
35fd0 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e  tabase N of conn
35fe0 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20  ection D.  ^The 
35ff0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
36000 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61  le.** has the na
36010 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74  me "main".  If t
36020 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63  here is no attac
36030 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f  hed database N o
36040 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
36050 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  * connection D, 
36060 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e  or if database N
36070 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20   is a temporary 
36080 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  or in-memory dat
36090 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61  abase, then.** a
360a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
360b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
360c0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72   ^The filename r
360d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
360e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20  function is the 
360f0 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a  output of the.**
36100 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d   xFullPathname m
36110 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46  ethod of the [VF
36120 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77  S].  ^In other w
36130 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61  ords, the filena
36140 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e  me.** will be an
36150 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61   absolute pathna
36160 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20  me, even if the 
36170 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a  filename used.**
36180 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
36190 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79  abase originally
361a0 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65   was a URI or re
361b0 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e  lative pathname.
361c0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
361d0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
361e0 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
361f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
36200 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
36210 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
36220 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
36230 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
36240 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36250 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
36260 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36270 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
36280 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
36290 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
362a0 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
362b0 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
362c0 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
362d0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
362e0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
362f0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69  nnection D..*/.i
36300 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  nt sqlite3_db_re
36310 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a  adonly(sqlite3 *
36320 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
36330 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
36340 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
36350 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
36360 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
36370 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
36380 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
36390 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
363a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
363b0 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
363c0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
363d0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
363e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
363f0 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73  b.  ^If pStmt is
36400 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
36410 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
36420 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
36430 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
36440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
36450 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
36460 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
36470 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
36480 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20  ^If no prepared 
36490 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
364a0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
364b0 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
364c0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
364d0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
364e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
364f0 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
36500 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
36510 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
36520 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
36530 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
36540 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
36550 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
36560 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
36570 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
36580 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
36590 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
365a0 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
365b0 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
365c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
365d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
365e0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
365f0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
36600 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
36610 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
36620 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
36630 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
36640 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
36650 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
36660 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
36670 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f  ansaction is [CO
36680 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64  MMIT | committed
36690 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
366a0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
366b0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
366c0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
366d0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
366e0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
366f0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
36700 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73  idden..** ^The s
36710 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36720 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
36730 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
36740 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
36750 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
36760 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
36770 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
36780 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
36790 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  k]..** ^Any call
367a0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
367b0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
367c0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
367d0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
367e0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
367f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
36800 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
36810 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
36820 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
36830 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
36840 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  k..** ^If the ca
36850 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
36860 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
36870 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
36880 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
36890 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
368a0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
368b0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ck..**.** ^The s
368c0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
368d0 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71  ok(D,C,P) and sq
368e0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
368f0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
36900 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ions.** return t
36910 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
36920 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
36930 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65  call of the same
36940 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20   function.** on 
36950 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
36960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36970 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
36980 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
36990 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f  for each functio
369a0 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68  n on D..**.** Th
369b0 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c  e commit and rol
369c0 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
369d0 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65  acks are not ree
369e0 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63  ntrant..** The c
369f0 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
36a00 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
36a10 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
36a20 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
36a30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
36a40 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
36a50 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
36a60 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
36a70 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
36a80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36a90 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
36aa0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
36ab0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
36ac0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
36ad0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
36ae0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
36af0 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
36b00 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
36b10 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
36b20 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
36b30 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65  running any othe
36b40 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
36b50 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45  , including SELE
36b60 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a  CT statements,.*
36b70 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c  * or merely call
36b80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
36b90 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
36ba0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36bb0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
36bc0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36bd0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
36be0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
36bf0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
36c00 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
36c10 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
36c20 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
36c30 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
36c40 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
36c50 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
36c60 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
36c70 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
36c80 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
36c90 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
36ca0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
36cb0 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
36cc0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
36cd0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
36ce0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
36cf0 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
36d00 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
36d10 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
36d20 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
36d30 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
36d40 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
36d50 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
36d60 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
36d70 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
36d80 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
36d90 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
36da0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
36db0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
36dc0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
36dd0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
36de0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
36df0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
36e00 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
36e10 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
36e20 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
36e30 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
36e40 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
36e50 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
36e60 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
36e70 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
36e80 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
36e90 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
36ea0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
36eb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
36ec0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
36ed0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
36ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
36ef0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
36f00 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
36f10 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
36f20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
36f30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
36f40 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
36f50 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
36f60 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
36f70 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36f80 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
36f90 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
36fa0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
36fb0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
36fc0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
36fd0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
36fe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36ff0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
37000 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
37010 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
37020 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
37030 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37040 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
37050 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
37060 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
37070 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
37080 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
37090 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
370a0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
370b0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
370c0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
370d0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
370e0 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
370f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
37100 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
37110 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
37120 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37130 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
37140 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
37150 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
37160 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
37170 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
37180 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
37190 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
371a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
371b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
371c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
371d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
371e0 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54  te_hook()..** ^T
371f0 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
37200 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
37210 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
37220 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
37230 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
37240 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
37250 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
37260 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
37270 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
37280 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
37290 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ked..** ^The thi
372a0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
372b0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
372c0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
372d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
372e0 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
372f0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
37300 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
37310 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20  ed row..** ^The 
37320 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
37330 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
37340 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
37350 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  ow..** ^In the c
37360 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
37370 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
37380 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
37390 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
373a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ce..**.** ^(The 
373b0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
373c0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
373d0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
373e0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
373f0 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
37400 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
37410 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
37420 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  )^.**.** ^In the
37430 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
37440 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
37450 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
37460 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
37470 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
37480 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
37490 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
374a0 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
374b0 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
374c0 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20  ] clause.  ^Nor 
374d0 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
374e0 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
374f0 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
37500 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
37510 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
37520 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
37530 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
37540 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
37550 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
37560 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
37570 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
37580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
37590 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
375a0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
375b0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
375c0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
375d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
375e0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
375f0 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
37600 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
37610 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
37620 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37630 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
37640 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
37650 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
37660 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
37670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
37680 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
37690 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
376a0 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
376b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
376c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
376d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
376e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
376f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
37700 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
37710 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
37720 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
37730 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  raph..**.** ^The
37740 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
37750 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
37760 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
37770 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
37780 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
37790 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20   call.** on the 
377a0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
377b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
377c0 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
377d0 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44   first call on D
377e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
377f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
37800 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64  mmit_hook()] and
37810 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
37820 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e  ck_hook()].** in
37830 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69  terfaces..*/.voi
37840 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
37850 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
37860 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
37870 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
37880 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
37890 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
378a0 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
378b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
378c0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
378d0 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
378e0 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  Cache.**.** ^(Th
378f0 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
37900 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
37910 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
37920 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
37930 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
37940 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
37950 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
37960 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
37970 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
37980 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
37990 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
379a0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
379b0 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
379c0 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
379d0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
379e0 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
379f0 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
37a00 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
37a10 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
37a20 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
37a30 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
37a40 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
37a50 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
37a60 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
37a70 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
37a80 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
37a90 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
37aa0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
37ab0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
37ac0 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
37ad0 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
37ae0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
37af0 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
37b00 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
37b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
37b20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
37b30 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
37b40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
37b50 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
37b60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37b70 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
37b80 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
37b90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
37ba0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
37bb0 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
37bc0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
37bd0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
37be0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
37bf0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
37c00 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
37c10 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
37c20 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
37c30 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
37c40 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
37c50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
37c60 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
37c70 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
37c80 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
37c90 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
37ca0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
37cb0 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
37cc0 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
37cd0 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
37ce0 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
37cf0 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
37d00 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
37d10 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
37d20 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
37d30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
37d40 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
37d50 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
37d60 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
37d70 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
37d80 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
37d90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
37da0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
37db0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
37dc0 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
37dd0 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
37de0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
37df0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
37e00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37e10 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
37e20 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
37e30 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
37e40 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
37e50 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
37e60 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
37e70 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
37e80 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
37e90 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
37ea0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37eb0 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
37ec0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
37ed0 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
37ee0 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
37ef0 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
37f00 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
37f10 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
37f20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
37f30 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
37f40 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
37f50 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
37f60 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
37f70 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
37f80 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
37f90 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
37fa0 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  NT]..**.** See a
37fb0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62  lso: [sqlite3_db
37fc0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37fd0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
37fe0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
37ff0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
38000 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d  PI3REF: Free Mem
38010 6f 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61  ory Used By A Da
38020 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
38030 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
38040 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f  ite3_db_release_
38050 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66  memory(D) interf
38060 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
38070 66 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61  free as much hea
38080 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70  p.** memory as p
38090 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74  ossible from dat
380a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
380b0 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a   D. Unlike the.*
380c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
380d0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74  se_memory()] int
380e0 65 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74  erface, this int
380f0 65 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74  erface is effect
38100 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68   even.** when th
38110 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  en [SQLITE_ENABL
38120 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
38130 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ENT] compile-tim
38140 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f  e option is.** o
38150 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  mitted..**.** Se
38160 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
38170 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38180 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
38190 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  3_db_release_mem
381a0 6f 72 79 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ory(sqlite3*);..
381b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
381c0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
381d0 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
381e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
381f0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
38200 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
38210 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73  s and/or queries
38220 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d   the.** soft lim
38230 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
38240 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
38250 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
38260 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
38270 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69  .** ^SQLite stri
38280 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70  ves to keep heap
38290 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74   memory utilizat
382a0 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  ion below the so
382b0 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74  ft heap.** limit
382c0 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65   by reducing the
382d0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
382e0 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67   held in the pag
382f0 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65  e cache.** as he
38300 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73  ap memory usages
38310 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20   approaches the 
38320 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  limit..** ^The s
38330 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
38340 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65  s "soft" because
38350 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c   even though SQL
38360 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73  ite strives to s
38370 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65  tay.** below the
38380 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20   limit, it will 
38390 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74  exceed the limit
383a0 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e   rather than gen
383b0 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c  erate.** an [SQL
383c0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72  ITE_NOMEM] error
383d0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
383e0 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  s, the soft heap
383f0 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64   limit .** is ad
38400 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
38410 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  ** ^The return v
38420 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
38430 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
38440 74 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a  t64() is the siz
38450 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74  e of.** the soft
38460 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f   heap limit prio
38470 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2c 20 6f  r to the call, o
38480 72 20 6e 65 67 61 74 69 76 65 20 69 6e 20 74 68  r negative in th
38490 65 20 63 61 73 65 20 6f 66 20 61 6e 0a 2a 2a 20  e case of an.** 
384a0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
384b0 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65  argument N is ne
384c0 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e  gative.** then n
384d0 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65  o change is made
384e0 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61   to the soft hea
384f0 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c  p limit.  Hence,
38500 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
38510 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74  size of the soft
38520 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20   heap limit can 
38530 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  be determined by
38540 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
38550 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
38560 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61 20  imit64() with a 
38570 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e  negative argumen
38580 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
38590 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a   argument N is z
385a0 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66  ero then the sof
385b0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
385c0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
385d0 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  ^(The soft heap 
385e0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66  limit is not enf
385f0 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75 72  orced in the cur
38600 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
38610 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72  ion.** if one or
38620 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69   more of followi
38630 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72  ng conditions ar
38640 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e true:.**.** <u
38650 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73  l>.** <li> The s
38660 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
38670 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  s set to zero..*
38680 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63  * <li> Memory ac
38690 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61  counting is disa
386a0 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d  bled using a com
386b0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  bination of the.
386c0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
386d0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
386e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
386f0 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69  S],...) start-ti
38700 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a  me option and.**
38710 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54        the [SQLIT
38720 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
38730 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  TUS] compile-tim
38740 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  e option..** <li
38750 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  > An alternative
38760 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
38770 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70  ementation is sp
38780 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a  ecified using.**
38790 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
387a0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
387b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2c 2e  ONFIG_PCACHE2],.
387c0 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ..)..** <li> The
387d0 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f   page cache allo
387e0 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f  cates from its o
387f0 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73  wn memory pool s
38800 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20  upplied.**      
38810 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  by [sqlite3_conf
38820 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
38830 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e  IG_PAGECACHE],..
38840 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a  .) rather than.*
38850 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20  *      from the 
38860 68 65 61 70