/ Hex Artifact Content
Login

Artifact e5552743b5b74dc675ebbdedd849ba8283424fa9:


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 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5740: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5750: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5760: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5770: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5780: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5790: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
57a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
57b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
57c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
57d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
57f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5800: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5810: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5820: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5830: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5850: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5860: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5870: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
58b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
58d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5900: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5910: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5920: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5940: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5950: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5960: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5980: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
59b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
59d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
59f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5a10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5a30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5aa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ac0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ae0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5af0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5b00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5b30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5bb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5bf0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5c30: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5c40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c60: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5c70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5c80: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5c90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cb0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5cd0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5ce0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d00: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5d10: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5d20: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d50: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5d60: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5d70: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5da0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5dc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5dd0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5df0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5e00: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5e10: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5e20: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5e30: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5e40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5e50: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5e60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e70: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5e80: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5e90: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5ea0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5eb0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5ec0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5ed0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5ee0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5ef0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5f00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5f20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5f30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5f60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5f70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5f80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5f90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5fa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5fb0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5fc0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5fd0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5fe0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5ff0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6000: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6010: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6020: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6030: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6040: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6050: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6060: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6070: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6080: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6090: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
60a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
60b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
60c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
60d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
60e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
60f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6100: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6110: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6120: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6130: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6140: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6150: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6160: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6170: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6180: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6190: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
61a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
61b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
61c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
61d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
61e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
61f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6200: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6220: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6230: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6240: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6250: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6260: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6270: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6280: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6290: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
62a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
62b0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
62c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
62e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
62f0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6300: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6320: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6350: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6370: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
63a0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
63b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
63c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
63d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63e0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
63f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6400: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6410: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6430: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6440: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6450: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6460: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6470: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6480: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
64a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
64b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
64c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
64e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
64f0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6510: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6520: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6540: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6550: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6560: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6570: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6580: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6590: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
65a0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
65b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
65c0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
65d0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
65e0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
65f0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6600: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6610: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6620: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6640: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6650: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6660: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6670: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6680: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6690: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
66b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
66c0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
66e0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
66f0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6700: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6710: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6720: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6730: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6740: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6760: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6770: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6780: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6790: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
67a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
67b0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
67c0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
67d0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
67e0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
67f0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6800: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6810: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6830: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6840: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6850: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6860: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6870: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6880: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6890: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
68a0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
68b0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
68c0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
68d0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
68e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
68f0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6900: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6920: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6930: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6940: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6950: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6960: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6970: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6980: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6990: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69a0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
69b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69c0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
69d0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
69e0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
69f0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6a00: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6a10: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6a20: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6a30: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6a40: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6a50: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6a60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6a80: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6a90: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6aa0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6ab0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6ac0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6ad0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6ae0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6af0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6b00: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6b10: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6b20: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6b30: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6b40: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6b50: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6b60: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6b70: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6b80: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6b90: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6ba0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6bb0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6bc0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6bd0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6be0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6bf0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6c10: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6c20: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6c30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c40: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6c50: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6c60: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6c70: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6c80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6c90: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6ca0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6cb0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6cc0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6cd0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6ce0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6cf0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6d00: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6d10: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6d20: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6d30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6d40: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6d50: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6d60: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6d70: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6d80: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6d90: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6da0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6db0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6dc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6de0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6df0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6e00: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6e10: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6e20: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6e30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e40: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6e50: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6e60: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6e70: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e80: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6e90: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6ea0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6eb0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6ed0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6ee0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6ef0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6f00: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6f10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6f20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6f30: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6f40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6f50: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6f60: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6f70: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6f80: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6f90: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6fa0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6fb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6fc0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6fd0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6fe0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6ff0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7000: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7010: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7020: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7030: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7040: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7050: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7060: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7070: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7080: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7090: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
70a0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
70b0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
70c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
70d0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
70e0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
70f0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7100: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7110: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7120: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7130: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7140: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7150: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7160: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7170: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7180: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7190: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
71a0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
71b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
71c0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
71d0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
71e0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
71f0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7200: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7230: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7240: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7250: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7260: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7270: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7280: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7290: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
72a0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
72b0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
72c0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
72d0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
72e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
72f0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7300: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7310: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7320: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7330: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7340: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7350: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7360: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7370: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7380: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7390: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
73b0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
73d0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
73e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73f0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7400: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7410: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7420: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7430: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7440: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7450: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7460: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7470: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7480: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7490: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
74a0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
74b0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
74c0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
74d0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
74e0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
74f0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7500: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7510: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7520: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7530: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7540: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7550: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7560: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7570: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7580: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7590: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
75a0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
75b0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
75c0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
75d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
75e0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
75f0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7600: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7610: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7620: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7630: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7640: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7650: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7660: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7670: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7680: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7690: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
76a0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
76b0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
76c0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
76d0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
76e0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
76f0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7700: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7710: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7720: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7730: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7740: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7750: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7760: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7770: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7780: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7790: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
77a0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
77b0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
77c0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
77d0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
77e0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
77f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7800: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7810: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7820: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7830: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7840: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7850: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7860: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7870: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7880: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7890: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
78a0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
78b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
78c0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
78d0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
78e0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
78f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7900: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7910: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
7920: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
7930: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7940: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7950: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7960: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7970: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7980: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7990: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
79a0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
79b0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
79c0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
79d0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
79e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7a00: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7a10: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7a20: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7a30: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7a40: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7a50: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7a60: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a80: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7aa0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ac0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
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: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7b10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b20: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b40: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b60: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7ba0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7bb0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7bc0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7bd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7be0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bf0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7c00: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7c10: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7c20: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7c30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7c40: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7c50: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7c60: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7c70: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7c80: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7c90: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7ca0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7cb0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7cc0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7cd0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7cf0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7d00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7d10: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7d20: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7d30: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7d40: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7d50: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7d60: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7d70: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7d80: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7d90: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7da0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7db0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7dc0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7dd0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7de0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7df0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7e00: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7e10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7e20: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7e30: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7e40: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7e50: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7e60: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7e70: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7e80: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7e90: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7ea0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7eb0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7ec0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7ed0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7ee0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7ef0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7f00: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7f10: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7f20: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7f30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7f40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7f50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f60: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7f70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7f80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7f90: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7fa0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7fb0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7fc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7fd0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7fe0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7ff0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8000: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8010: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8020: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8030: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8040: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8050: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8060: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8070: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8080: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8090: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
80a0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
80b0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
80c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
80d0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
80e0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
80f0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8100: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8110: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8120: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8130: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8140: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8150: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8160: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8170: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8180: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8190: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
81a0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
81b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
81c0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
81d0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
81e0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
81f0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8200: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8210: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8220: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8230: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8240: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8250: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8260: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8270: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8280: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8290: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
82a0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
82b0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
82c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
82d0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
82e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
82f0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8300: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8310: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8320: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
8330: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8340: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8350: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8360: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8370: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8380: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8390: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
83a0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
83b0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
83c0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
83d0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
83e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
83f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8400: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8420: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8430: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8440: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8450: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8460: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8470: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8480: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8490: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
84a0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
84b0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
84c0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
84d0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
84e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
84f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8500: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8510: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8520: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8530: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8540: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8550: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8560: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8570: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8580: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8590: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
85a0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
85b0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
85c0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
85d0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
85e0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
85f0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8600: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8610: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8630: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8640: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8650: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8660: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8670: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8680: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8690: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
86a0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
86b0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
86c0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
86d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
86e0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
86f0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8700: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8710: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8720: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8730: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8740: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8750: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8760: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8770: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8780: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8790: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
87a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
87b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
87c0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
87d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
87e0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
87f0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8800: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8810: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8820: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8830: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8840: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8850: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8860: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8870: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8890: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
88a0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
88b0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
88c0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
88d0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
88e0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
88f0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8900: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8910: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8920: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8930: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8940: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8950: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8960: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8970: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8980: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8990: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
89a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
89b0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
89c0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
89d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
89e0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
89f0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8a00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8a10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a20: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8a30: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8a40: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8a50: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8a60: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8a80: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8a90: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8aa0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8ab0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8ac0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8ad0: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8ae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8af0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8b00: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8b10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8b20: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8b30: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8b40: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8b50: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8b60: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8b70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8b80: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8b90: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8ba0: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8bb0: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8bc0: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8bd0: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8be0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8bf0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8c00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8c10: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8c20: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8c30: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8c40: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8c50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8c60: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8c70: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8c80: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8c90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8ca0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8cb0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8cc0: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8cd0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8ce0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8cf0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8d00: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8d10: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8d20: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8d30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d40: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8d50: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8d60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8d70: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8d80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8d90: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8da0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8db0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8dc0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8dd0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8de0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8df0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8e00: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8e10: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8e20: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8e30: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8e40: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e50: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8e60: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8e70: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8e80: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8e90: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8ea0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8eb0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8ec0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8ed0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8ee0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8ef0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8f00: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8f10: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8f20: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8f30: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8f40: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8f50: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8f60: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8f70: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
8f80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
8f90: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
8fa0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
8fb0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
8fc0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
8fd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8fe0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8ff0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9000: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9010: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9020: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9030: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9040: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9050: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9060: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9070: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9080: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9090: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
90a0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
90b0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
90c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
90d0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
90e0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
90f0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9100: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9110: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9120: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9130: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9140: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9150: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9160: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9170: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9180: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9190: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
91a0: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
91b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
91c0: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
91d0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
91e0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
91f0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9200: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9210: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9220: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9230: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9240: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9250: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9260: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9270: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9280: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9290: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
92a0: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
92b0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
92c0: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
92d0: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
92e0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
92f0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9300: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9310: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9320: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9330: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9340: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9350: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9360: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9370: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9380: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9390: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
93a0: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
93b0: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
93c0: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
93d0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
93e0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
93f0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9400: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9410: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
9420: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
9430: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9440: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9450: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9460: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9480: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9490: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
94a0: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
94b0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
94c0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
94d0: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
94e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
94f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9500: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9510: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9520: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
9530: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9550: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9560: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9570: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9580: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9590: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
95a0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
95b0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
95c0: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
95d0: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
95e0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
95f0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
9600: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
9610: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
9620: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
9630: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9640: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9650: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9660: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9670: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9680: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9690: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
96a0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
96b0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
96c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
96d0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
96e0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
96f0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9700: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
9710: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
9720: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9730: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9740: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9750: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9760: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9770: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9780: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9790: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
97a0: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
97b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
97c0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
97d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
97e0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
97f0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
9800: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
9810: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
9820: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
9830: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9840: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9850: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9860: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9870: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9880: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9890: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
98a0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
98b0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
98c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
98d0: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
98e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
98f0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
9900: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
9910: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
9920: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
9930: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9940: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9950: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9960: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9970: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9980: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
99a0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
99b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
99c0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
99d0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
99e0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
99f0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9a00: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9a10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9a20: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9a30: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9a40: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9a50: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9a60: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9a70: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9a80: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9a90: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9aa0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9ab0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9ac0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9ad0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9ae0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9af0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9b00: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9b10: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9b20: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9b30: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9b40: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9b50: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9b60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9b70: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9b80: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9ba0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9bb0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9bc0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9bd0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9be0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9bf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9c00: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9c10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9c20: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9c30: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9c40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9c50: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9c60: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9c70: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9c80: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9c90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9ca0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9cb0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9cc0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9cd0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9ce0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9cf0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9d00: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9d10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9d20: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9d30: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9d50: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9d60: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9d70: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9d80: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9d90: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9da0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9db0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9dc0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9dd0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9de0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9df0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9e00: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9e10: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9e20: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9e30: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9e40: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9e50: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9e60: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9e70: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9e80: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9e90: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9ea0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9eb0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9ec0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9ed0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9ee0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9ef0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9f00: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9f10: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9f20: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9f30: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9f40: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9f50: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9f60: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9f70: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
9f80: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
9f90: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
9fa0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
9fb0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
9fc0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
9fd0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
9fe0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9ff0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a000: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a010: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a020: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a030: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a040: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a050: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a060: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a070: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a080: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a090: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a0a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a0b0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a0c0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a0d0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a0e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a0f0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a100: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a110: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a120: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a130: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a140: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a150: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a160: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a170: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
a180: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a190: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a1a0: 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 2d  ].** ^This file-
a1b0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
a1c0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a1d0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
a1e0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
a1f0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
a200: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
a210: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
a220: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
a230: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
a240: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
a250: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
a260: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
a270: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
a280: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
a290: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
a2a0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
a2b0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
a2c0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
a2d0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
a2e0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
a2f0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
a300: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
a310: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
a320: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
a330: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
a340: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
a350: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
a360: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
a370: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
a380: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
a390: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
a3a0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
a3b0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
a3c0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
a3d0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
a3e0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
a3f0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
a400: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
a410: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
a420: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a430: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
a440: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
a450: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
a460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a470: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
a480: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
a490: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
a4a0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
a4b0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
a4c0: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
a4d0: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
a4e0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
a4f0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
a500: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
a510: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
a520: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
a530: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
a540: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
a550: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
a560: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
a570: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a580: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a590: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
a5a0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
a5b0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
a5c0: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
a5d0: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
a5e0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
a5f0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
a600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a610: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
a620: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
a630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
a640: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
a650: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
a660: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
a670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
a680: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
a690: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
a6a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
a6b0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
a6c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
a6d0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
a6e0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
a6f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
a700: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
a710: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
a720: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
a730: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
a740: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
a750: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
a760: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
a770: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
a780: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a790: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
a7a0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
a7b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a7c0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
a7d0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
a7e0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a7f0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
a800: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
a810: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
a820: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a830: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a840: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a850: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
a860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a870: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
a880: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
a890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a8a0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a8b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
a8c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a8d0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
a8e0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 0a 2f             16../
a8f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
a900: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
a910: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
a920: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
a930: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
a940: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
a950: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
a960: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
a970: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
a980: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
a990: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
a9a0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
a9b0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
a9c0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
a9d0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
a9e0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
a9f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
aa00: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
aa10: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
aa20: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
aa30: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
aa40: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
aa50: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
aa60: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
aa70: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
aa80: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
aa90: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
aaa0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
aab0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
aac0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
aad0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
aae0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
aaf0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
ab00: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
ab10: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
ab20: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
ab30: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
ab40: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
ab50: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
ab60: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
ab70: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
ab80: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
ab90: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
aba0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
abb0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
abc0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
abd0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
abe0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
abf0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
ac00: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
ac10: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
ac20: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
ac30: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
ac40: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
ac50: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
ac60: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
ac70: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
ac80: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
ac90: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
aca0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
acb0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
acc0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
acd0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
ace0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
acf0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
ad00: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
ad10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
ad20: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
ad30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
ad40: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
ad50: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
ad60: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
ad70: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
ad80: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
ad90: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
ada0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
adb0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
adc0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
add0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
ade0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
adf0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
ae00: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
ae10: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
ae20: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
ae30: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
ae40: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
ae50: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
ae60: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
ae70: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
ae80: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
ae90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
aea0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
aeb0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
aec0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
aed0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
aee0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
aef0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
af00: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
af10: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
af20: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
af30: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
af40: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
af50: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
af60: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
af70: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
af80: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
af90: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
afa0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
afb0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
afc0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
afd0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
afe0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
aff0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
b000: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
b010: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
b020: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
b030: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
b040: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
b050: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
b060: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
b070: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
b080: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
b090: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
b0a0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
b0b0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
b0c0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b0d0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
b0e0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
b0f0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
b100: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
b110: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
b120: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
b130: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
b140: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
b150: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
b160: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
b170: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
b180: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
b190: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
b1a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b1b0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
b1c0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
b1d0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
b1e0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
b1f0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
b200: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
b210: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
b220: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
b230: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
b240: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
b250: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
b260: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
b270: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
b280: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
b290: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
b2a0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
b2b0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
b2c0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
b2d0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
b2e0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
b2f0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
b300: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
b310: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
b320: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
b330: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
b340: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
b350: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b360: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
b370: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
b380: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
b390: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
b3a0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
b3b0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
b3c0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
b3d0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
b3e0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
b3f0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
b400: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
b410: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
b420: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
b430: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
b440: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b450: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
b460: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
b470: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
b480: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
b490: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
b4a0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
b4b0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
b4c0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
b4d0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
b4e0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
b4f0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
b500: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
b510: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
b520: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
b530: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
b540: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
b550: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
b560: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
b570: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
b580: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
b590: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
b5a0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
b5b0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
b5c0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
b5d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
b5e0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
b5f0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
b600: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
b610: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
b620: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
b630: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b640: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
b650: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b660: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
b670: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b680: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
b690: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b6a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
b6b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
b6c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
b6d0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
b6e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b6f0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
b700: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b710: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
b720: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b730: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
b740: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
b750: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
b760: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
b770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
b780: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
b790: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
b7a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
b7b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b7c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
b7d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
b7e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
b7f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
b800: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
b810: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
b820: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
b830: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
b840: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
b850: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
b860: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
b870: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
b880: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
b890: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
b8a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
b8b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
b8c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
b8d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
b8e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
b8f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
b900: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
b910: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
b920: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
b930: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
b940: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
b950: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
b960: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
b970: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
b980: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
b990: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
b9a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
b9b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
b9c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
b9d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
b9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
b9f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
ba00: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
ba10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
ba20: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
ba30: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
ba40: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
ba50: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
ba60: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
ba70: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ba80: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
ba90: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
baa0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
bab0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
bac0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
bad0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
bae0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
baf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
bb00: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
bb10: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
bb20: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
bb30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
bb40: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
bb50: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
bb60: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
bb70: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
bb80: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
bb90: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
bba0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
bbb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
bbc0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
bbd0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
bbe0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
bbf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
bc00: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
bc10: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
bc20: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
bc30: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
bc40: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
bc50: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
bc60: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
bc70: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
bc80: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
bc90: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
bca0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
bcb0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
bcc0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
bcd0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
bce0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
bcf0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
bd00: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
bd10: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
bd20: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
bd30: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
bd40: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
bd50: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
bd60: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
bd70: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
bd80: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
bd90: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
bda0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
bdb0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
bdc0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
bdd0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
bde0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
bdf0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
be00: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
be10: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
be20: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
be30: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
be40: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
be50: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
be60: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
be70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
be80: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
be90: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
bea0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
beb0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
bec0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
bed0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
bee0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
bef0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
bf00: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
bf10: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
bf20: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
bf30: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
bf40: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
bf50: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
bf60: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
bf70: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
bf80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
bf90: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
bfa0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
bfb0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
bfc0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
bfd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
bfe0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
bff0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
c000: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
c010: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
c020: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
c030: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
c040: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
c050: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
c060: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
c070: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
c080: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
c090: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
c0a0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
c0b0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
c0c0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
c0d0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
c0e0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
c0f0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
c100: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
c110: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
c120: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
c130: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
c140: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
c150: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
c160: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
c170: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
c180: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c190: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
c1a0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
c1b0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
c1c0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
c1d0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
c1e0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
c1f0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
c200: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
c210: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
c220: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c230: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
c240: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
c250: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
c260: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
c270: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
c280: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
c290: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
c2a0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
c2b0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
c2c0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
c2d0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
c2e0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
c2f0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
c300: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
c310: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
c320: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
c330: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
c340: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
c350: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
c360: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
c370: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
c380: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
c390: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
c3a0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
c3b0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
c3c0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
c3d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
c3e0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
c3f0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
c400: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
c410: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
c420: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
c430: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
c440: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
c450: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c460: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
c470: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
c480: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
c490: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
c4a0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
c4b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
c4c0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
c4d0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
c4e0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
c4f0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
c500: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c510: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
c520: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
c530: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
c540: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
c550: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
c560: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
c570: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
c580: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
c590: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
c5a0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
c5b0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
c5c0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
c5d0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
c5e0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
c5f0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
c600: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
c610: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
c620: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
c630: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
c640: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
c650: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
c660: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
c670: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
c680: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
c690: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
c6a0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
c6b0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
c6c0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
c6d0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
c6e0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
c6f0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
c700: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
c710: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
c720: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
c730: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
c740: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
c750: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
c760: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
c770: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
c780: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
c790: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
c7a0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
c7b0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
c7c0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
c7d0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
c7e0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
c7f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
c800: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
c810: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
c820: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
c830: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
c840: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
c850: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
c860: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
c870: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
c880: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
c890: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
c8a0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
c8b0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
c8c0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
c8d0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
c8e0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
c8f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
c900: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
c910: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
c920: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c930: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
c940: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
c950: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
c960: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
c970: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c980: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
c990: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
c9a0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
c9b0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
c9c0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
c9d0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
c9e0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
c9f0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
ca00: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
ca10: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
ca20: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
ca30: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
ca40: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
ca50: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
ca60: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
ca70: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
ca80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ca90: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
caa0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
cab0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
cac0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
cad0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
cae0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
caf0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
cb00: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
cb10: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
cb20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
cb30: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
cb40: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
cb50: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
cb60: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
cb70: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
cb80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cb90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cba0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
cbb0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
cbc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cbd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cbe0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
cbf0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
cc00: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
cc10: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
cc20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
cc30: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
cc40: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
cc50: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
cc60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cc70: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
cc80: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
cc90: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
cca0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
ccb0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
ccc0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
ccd0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
cce0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
ccf0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
cd00: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
cd10: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
cd20: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
cd30: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
cd40: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
cd50: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
cd60: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
cd70: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
cd80: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
cd90: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
cda0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
cdb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
cdc0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
cdd0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
cde0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
cdf0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
ce00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ce10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ce20: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
ce30: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
ce40: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
ce50: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
ce60: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
ce70: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
ce80: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
ce90: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
cea0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
ceb0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
cec0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
ced0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
cee0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
cef0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
cf00: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cf10: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
cf20: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
cf30: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
cf40: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
cf50: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
cf60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cf70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cf80: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
cf90: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
cfa0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
cfb0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
cfc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
cfd0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
cfe0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
cff0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
d000: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d010: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d020: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
d030: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
d040: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
d050: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
d060: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d070: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
d080: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
d090: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
d0a0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
d0b0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
d0c0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
d0d0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
d0e0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
d0f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d100: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d110: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
d120: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
d130: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
d140: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
d150: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
d160: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
d170: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
d180: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
d190: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
d1a0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
d1b0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
d1c0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
d1d0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
d1e0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
d1f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d200: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
d210: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
d220: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
d230: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
d240: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
d250: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d260: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
d270: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d280: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
d290: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
d2a0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
d2b0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
d2c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d2d0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
d2e0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
d2f0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
d300: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
d310: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
d320: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d330: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
d340: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
d350: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
d360: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
d370: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
d380: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
d390: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
d3a0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
d3b0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
d3c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d3d0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
d3e0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d3f0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
d400: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
d410: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
d420: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
d430: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
d440: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
d450: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
d460: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
d470: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
d480: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
d490: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d4a0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
d4b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d4c0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
d4d0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
d4e0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
d4f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
d500: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d510: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
d520: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
d530: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
d540: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
d550: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d560: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d570: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
d580: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
d590: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
d5a0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
d5b0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
d5c0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
d5d0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
d5e0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
d5f0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
d600: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
d610: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
d620: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
d630: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d640: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
d650: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
d660: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
d670: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d680: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
d690: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
d6a0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
d6b0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
d6c0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
d6d0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d6e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
d6f0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
d700: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
d710: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
d720: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
d730: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
d740: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
d750: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
d760: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
d770: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
d780: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d790: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
d7a0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
d7b0: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
d7c0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
d7d0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
d7e0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
d7f0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
d800: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
d810: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
d830: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
d840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
d850: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
d860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
d870: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
d880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d890: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
d8a0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
d8b0: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
d8c0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
d8d0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
d8e0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
d8f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
d900: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
d910: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
d920: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
d930: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
d940: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
d950: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
d960: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
d970: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
d980: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
d990: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
d9a0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
d9b0: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
d9c0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
d9d0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
d9e0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
d9f0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
da00: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
da10: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
da20: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
da30: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
da40: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
da50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
da60: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
da70: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
da80: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
da90: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
daa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
dab0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
dac0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
dad0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
dae0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
daf0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
db00: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
db10: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
db20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
db30: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
db40: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
db50: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
db60: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
db70: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
db80: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
db90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
dba0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
dbb0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
dbc0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
dbd0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dbe0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
dbf0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
dc00: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
dc10: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
dc20: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
dc30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dc40: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
dc50: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
dc60: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
dc70: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
dc80: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
dc90: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
dca0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dcb0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
dcc0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
dcd0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
dce0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
dcf0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
dd00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
dd10: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
dd20: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
dd30: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
dd40: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
dd50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
dd60: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
dd70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dd80: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
dd90: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
dda0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ddb0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
ddc0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
ddd0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
dde0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
ddf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
de00: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
de10: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
de20: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
de30: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
de40: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
de50: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
de60: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
de70: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
de80: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
de90: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
dea0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
deb0: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
dec0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
ded0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dee0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
def0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
df00: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
df10: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
df20: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
df30: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
df40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
df50: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
df60: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
df70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
df80: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
df90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
dfa0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
dfb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dfc0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
dfd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
dfe0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
dff0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e000: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
e010: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
e020: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
e030: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
e040: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
e050: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
e060: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
e070: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
e080: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
e090: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
e0a0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
e0b0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
e0c0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
e0d0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
e0e0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
e0f0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
e100: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
e110: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
e120: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
e130: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
e140: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
e150: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
e160: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
e170: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
e180: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
e190: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
e1a0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e1b0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
e1c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
e1d0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
e1e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e1f0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
e200: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
e210: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
e220: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
e230: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
e240: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
e250: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
e260: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
e270: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
e280: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
e290: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
e2a0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
e2b0: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
e2c0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
e2d0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
e2e0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
e2f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
e300: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
e310: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e320: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
e330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e340: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
e350: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
e360: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
e370: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
e380: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
e390: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
e3a0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
e3b0: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
e3c0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e3d0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
e3e0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
e3f0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e400: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e410: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
e420: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
e430: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
e440: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
e450: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
e460: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
e470: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
e480: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
e490: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
e4a0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
e4b0: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
e4c0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
e4d0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
e4e0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
e4f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
e500: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
e510: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
e520: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
e530: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
e540: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
e550: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
e560: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
e570: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
e580: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
e590: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
e5a0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
e5b0: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
e5c0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
e5d0: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
e5e0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
e5f0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
e600: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
e610: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
e620: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
e630: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
e640: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
e650: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
e660: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
e670: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
e680: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
e690: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
e6a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e6b0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
e6c0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
e6d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
e6e0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
e6f0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
e700: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e710: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
e720: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
e730: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
e740: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e750: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
e760: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
e770: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
e780: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
e790: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
e7a0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
e7b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
e7c0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
e7d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e7e0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
e7f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
e800: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
e810: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
e820: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
e830: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
e840: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
e850: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
e860: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
e870: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
e880: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
e890: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
e8a0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
e8b0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
e8c0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
e8d0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
e8e0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
e8f0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
e900: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
e910: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
e920: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e930: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e940: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
e950: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
e960: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
e970: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
e980: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
e990: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
e9a0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
e9b0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
e9c0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
e9d0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
e9e0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
e9f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
ea00: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
ea10: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
ea20: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
ea30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
ea40: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
ea50: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
ea60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ea70: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
ea80: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
ea90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
eaa0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
eab0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
eac0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
ead0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
eae0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
eaf0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
eb00: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
eb10: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
eb20: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
eb30: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
eb40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
eb50: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
eb60: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
eb70: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
eb80: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
eb90: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
eba0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
ebb0: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
ebc0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
ebd0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
ebe0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
ebf0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
ec00: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ec10: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
ec20: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
ec30: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
ec40: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
ec50: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
ec60: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
ec70: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
ec80: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
ec90: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
eca0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
ecb0: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
ecc0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
ecd0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
ece0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
ecf0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
ed00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
ed10: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
ed20: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
ed30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ed40: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
ed50: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
ed60: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
ed70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ed80: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
ed90: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
eda0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
edb0: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
edc0: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
edd0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
ede0: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
edf0: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ee00: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ee10: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ee20: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
ee30: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
ee40: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
ee50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
ee60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ee70: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ee80: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ee90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
eea0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
eeb0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
eec0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
eed0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
eee0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
eef0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
ef00: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
ef10: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
ef20: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
ef30: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ef40: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
ef50: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
ef60: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
ef70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ef80: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
ef90: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
efa0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
efb0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
efc0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
efd0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
efe0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
eff0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
f000: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
f010: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
f020: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
f030: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f040: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
f050: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f070: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
f080: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
f090: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
f0a0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
f0b0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
f0c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
f0d0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
f0e0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
f0f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f100: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
f110: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
f120: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
f130: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f140: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
f150: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f160: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
f170: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f180: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
f190: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
f1a0: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
f1b0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
f1c0: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
f1d0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
f1e0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
f1f0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
f200: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
f210: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
f220: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
f230: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
f240: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
f250: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
f260: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
f270: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
f280: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
f290: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
f2a0: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
f2b0: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
f2c0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
f2d0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
f2e0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
f2f0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
f300: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
f310: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
f320: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
f330: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
f340: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
f350: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
f360: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
f370: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
f380: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
f390: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
f3a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f3b0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f3c0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
f3d0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
f3e0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
f3f0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
f400: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
f410: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f420: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
f430: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
f440: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f450: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
f460: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f470: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
f480: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
f490: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f4a0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
f4b0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
f4c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
f4d0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
f4e0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
f4f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
f500: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f510: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
f520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
f530: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
f540: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
f550: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
f560: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
f570: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
f580: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
f590: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
f5a0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
f5b0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
f5c0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
f5d0: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
f5e0: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
f5f0: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
f600: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
f610: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
f620: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
f630: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
f640: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
f650: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
f660: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
f670: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
f680: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
f690: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
f6a0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
f6b0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
f6c0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
f6d0: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
f6e0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
f6f0: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
f700: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
f710: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
f720: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f730: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
f740: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
f750: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
f760: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
f770: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
f780: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
f790: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
f7a0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
f7b0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
f7c0: 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
f7d0: 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
f7e0: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
f7f0: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
f800: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
f810: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
f820: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
f830: 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
f840: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
f850: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
f860: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
f870: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
f880: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
f890: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
f8a0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
f8b0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
f8c0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
f8d0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
f8e0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
f8f0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
f900: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
f910: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
f920: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
f930: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
f940: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
f950: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
f960: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
f970: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
f980: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
f990: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
f9a0: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
f9b0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
f9c0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
f9d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
f9e0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
f9f0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
fa00: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
fa10: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
fa20: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
fa30: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
fa40: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
fa50: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
fa60: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
fa70: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
fa80: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
fa90: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
faa0: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
fab0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
fac0: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
fad0: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
fae0: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
faf0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
fb00: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
fb10: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
fb20: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
fb30: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
fb40: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
fb50: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
fb60: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
fb70: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
fb80: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
fb90: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
fba0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
fbb0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
fbc0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
fbd0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
fbe0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
fbf0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
fc00: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
fc10: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
fc20: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
fc30: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
fc40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fc50: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
fc60: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
fc70: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
fc80: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
fc90: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
fca0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
fcb0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
fcc0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
fcd0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
fce0: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
fcf0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
fd00: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
fd10: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
fd20: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
fd30: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
fd40: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
fd50: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
fd60: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
fd70: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
fd80: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
fd90: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
fda0: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
fdb0: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
fdc0: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
fdd0: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
fde0: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
fdf0: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
fe00: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
fe10: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
fe20: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
fe30: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
fe40: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
fe50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fe60: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
fe70: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
fe80: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
fe90: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
fea0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
feb0: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
fec0: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
fed0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
fee0: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
fef0: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
ff00: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
ff10: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
ff20: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
ff30: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
ff40: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
ff50: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
ff60: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
ff70: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
ff80: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
ff90: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
ffa0: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
ffb0: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
ffc0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
ffd0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
ffe0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
fff0: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
10000 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
10010 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
10020 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
10030 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
10040 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
10050 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
10060 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
10070 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
10080 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
10090 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
100a0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
100b0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
100c0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
100d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
100e0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
100f0 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
10100 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
10110 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10120 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
10130 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
10140 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
10150 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
10160 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
10170 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
10180 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
10190 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
101a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
101b0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
101c0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
101d0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
101e0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
101f0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
10200 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
10220 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
10230 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
10240 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
10250 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10260 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
10270 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
10280 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
10290 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
102a0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
102b0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
102c0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
102d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
102e0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
102f0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
10300 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
10310 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10320 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
10330 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
10340 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
10350 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
10360 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
10370 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
10380 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
10390 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
103a0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
103b0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
103c0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
103d0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
103e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
103f0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
10400 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
10410 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
10420 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
10430 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
10440 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
10450 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10460 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
10470 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
10480 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
10490 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
104a0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
104b0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
104c0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
104d0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
104e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
104f0 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
10500 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
10510 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
10520 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
10530 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
10540 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
10550 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
10560 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
10570 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
10580 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
10590 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
105a0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
105b0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
105c0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
105d0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
105e0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
105f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10600 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10610 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10620 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10630 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10640 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10650 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10660 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
10670 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
10680 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
10690 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
106a0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
106b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
106c0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
106d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
106e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
106f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
10700 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
10710 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
10720 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
10730 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10740 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10750 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10760 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10770 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
10780 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
10790 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
107a0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
107b0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
107c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
107d0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
107e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
107f0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
10800 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
10810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10820 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
10830 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
10840 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
10850 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
10860 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
10870 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
10880 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10890 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
108a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
108b0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
108c0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
108d0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
108e0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
108f0 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
10900 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
10910 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
10920 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
10930 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
10940 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
10950 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10960 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
10970 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
10980 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10990 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
109a0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
109b0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
109c0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
109d0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
109e0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
109f0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
10a00 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
10a10 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
10a20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
10a30 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10a40 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
10a50 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
10a60 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
10a70 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10a80 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
10a90 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
10aa0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
10ab0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
10ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10ad0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
10ae0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
10af0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
10b00 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
10b10 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
10b20 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
10b30 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
10b40 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
10b50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
10b60 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
10b70 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
10b80 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
10b90 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
10ba0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
10bb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
10bc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
10bd0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
10be0 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
10bf0 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
10c00 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
10c10 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
10c30 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
10c40 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
10c50 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
10c60 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
10c70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10c80 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
10c90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
10ca0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
10cb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
10cc0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
10cd0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
10ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
10cf0 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
10d00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
10d10 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
10d20 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
10d30 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
10d40 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10d50 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10d60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10d70 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10d80 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10d90 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10da0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10db0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10dc0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
10dd0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
10de0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10df0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
10e00 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
10e10 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
10e20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
10e30 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
10e40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10e50 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10e60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10e70 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
10e80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10e90 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
10ea0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
10eb0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
10ec0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
10ed0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
10ee0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
10ef0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
10f00 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10f10 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
10f20 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
10f30 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
10f40 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
10f50 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
10f60 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
10f70 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
10f80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10f90 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
10fa0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
10fb0 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
10fc0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
10fd0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
10fe0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
10ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
11000 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
11010 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
11020 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
11030 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
11040 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11050 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
11060 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11070 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
11080 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11090 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
110a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
110b0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
110c0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
110d0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
110e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
110f0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11100 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11110 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
11120 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
11130 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
11140 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
11150 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11160 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11170 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11180 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11190 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
111a0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
111b0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
111c0 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
111d0 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
111e0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
111f0 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
11200 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
11210 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
11220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11230 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
11240 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11250 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
11260 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11270 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
11280 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
11290 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
112a0 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
112b0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
112c0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
112d0 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
112e0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
112f0 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
11300 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
11310 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11320 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
11330 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
11340 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
11350 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
11360 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
11370 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
11380 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11390 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
113a0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
113b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
113c0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
113d0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
113e0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
113f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11400 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
11410 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
11420 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11430 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
11440 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11450 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
11460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
11470 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
11480 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
11490 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
114a0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
114b0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
114c0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
114d0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
114e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
114f0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
11500 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11510 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
11520 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11530 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
11540 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
11550 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
11560 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
11570 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
11580 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11590 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
115a0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
115b0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
115c0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
115d0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
115e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
115f0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
11600 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
11610 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
11620 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
11630 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
11640 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
11650 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
11660 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
11670 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
11680 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
11690 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
116a0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
116b0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
116c0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
116d0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
116e0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
116f0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
11700 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
11710 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
11720 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
11730 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
11740 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
11750 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
11760 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
11770 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
11780 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
11790 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
117a0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
117b0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
117c0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
117d0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
117e0 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
117f0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
11800 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
11810 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
11820 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
11830 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
11840 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
11850 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
11860 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
11870 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
11880 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
11890 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
118a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
118b0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
118c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
118d0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
118e0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
118f0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
11900 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
11910 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
11920 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
11930 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
11940 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
11950 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
11960 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
11970 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
11980 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
11990 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
119a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
119b0 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
119c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
119d0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
119e0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
119f0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
11a00 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
11a10 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
11a20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
11a30 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
11a40 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
11a50 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
11a60 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
11a70 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
11a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
11a90 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
11aa0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
11ab0 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
11ac0 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
11ad0 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
11ae0 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
11af0 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
11b00 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
11b10 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
11b20 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
11b30 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
11b40 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
11b50 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
11b60 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
11b70 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
11b80 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
11b90 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
11ba0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
11bb0 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
11bc0 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
11bd0 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
11be0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
11bf0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
11c00 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
11c10 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11c20 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11c30 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
11c40 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
11c50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
11c60 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
11c70 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
11c80 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
11c90 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
11ca0 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
11cb0 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
11cc0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
11cd0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
11ce0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
11cf0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
11d00 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
11d10 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
11d20 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
11d30 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
11d40 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
11d50 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
11d60 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
11d70 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11d80 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
11d90 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
11da0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
11db0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
11dc0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
11dd0 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
11de0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11df0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
11e00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11e10 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
11e20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
11e30 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
11e40 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11e50 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
11e60 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
11e70 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
11e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11e90 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
11ea0 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
11eb0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
11ec0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
11ed0 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
11ee0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
11ef0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11f00 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
11f10 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
11f20 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
11f30 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
11f40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
11f50 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
11f60 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
11f70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
11f80 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
11f90 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
11fa0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
11fb0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
11fc0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
11fd0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
11fe0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
11ff0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
12000 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
12010 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
12020 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
12030 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
12040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12050 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
12060 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
12070 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
12080 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
12090 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
120a0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
120b0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
120c0 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
120d0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
120e0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
120f0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
12100 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
12110 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
12120 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12130 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
12140 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
12150 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
12160 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
12170 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
12180 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12190 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
121a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
121b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
121c0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
121d0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
121e0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
121f0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
12200 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
12210 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12220 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
12230 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
12240 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12250 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
12260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12270 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
12280 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12290 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
122a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
122b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
122c0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
122d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
122e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
122f0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
12300 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12310 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12320 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
12330 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
12340 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
12350 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
12360 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12370 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
12380 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
12390 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
123a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
123b0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
123c0 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
123d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
123e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
123f0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
12400 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12410 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12420 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12430 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12440 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12450 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12460 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12470 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12480 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12490 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
124a0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
124b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
124c0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
124d0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
124e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
124f0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
12500 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12510 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
12520 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12530 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
12540 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
12550 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
12560 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12570 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12580 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12590 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
125a0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
125b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
125c0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
125d0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
125e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
125f0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
12600 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
12610 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
12620 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
12630 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
12640 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
12650 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
12660 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
12670 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
12680 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12690 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
126a0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
126b0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
126c0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
126d0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
126e0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
126f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12700 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12710 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12720 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12730 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12740 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12750 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
12760 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
12770 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
12780 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
12790 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
127a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
127b0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
127c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
127d0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
127e0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
127f0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
12800 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
12810 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12820 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
12830 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12840 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
12850 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12860 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
12870 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
12880 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
12890 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
128a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
128b0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
128c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
128d0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
128e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
128f0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12900 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
12910 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
12920 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
12930 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
12940 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12950 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
12960 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
12970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
12980 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
12990 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
129a0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
129b0 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
129c0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
129d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
129e0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
129f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
12a00 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
12a10 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
12a20 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
12a30 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
12a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
12a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
12a70 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
12a90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12aa0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12ab0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12ac0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
12ad0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
12ae0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
12af0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
12b00 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
12b10 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
12b20 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
12b30 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
12b40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
12b50 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
12b60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
12b70 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
12b80 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
12b90 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
12ba0 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
12bb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12bc0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
12bd0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12be0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
12bf0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12c00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12c10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12c20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12c30 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
12c40 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
12c50 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
12c60 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
12c70 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
12c80 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
12c90 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
12ca0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
12cb0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12cc0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
12cd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12ce0 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
12cf0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
12d00 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
12d10 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
12d20 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
12d30 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
12d40 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
12d50 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
12d60 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
12d70 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
12d80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
12d90 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
12da0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
12db0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
12dc0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
12dd0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
12de0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
12df0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
12e00 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
12e10 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
12e20 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
12e30 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
12e40 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
12e50 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
12e60 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
12e70 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12e80 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
12e90 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
12ea0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
12eb0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12ec0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
12ed0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
12ee0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
12ef0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
12f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
12f10 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
12f20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
12f30 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
12f40 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
12f50 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
12f60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
12f70 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
12f80 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
12f90 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
12fa0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
12fb0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
12fc0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
12fd0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
12fe0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
12ff0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
13000 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
13010 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
13020 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
13030 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
13040 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
13050 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
13060 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
13070 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
13080 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
13090 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
130a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
130b0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
130c0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
130d0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
130e0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
130f0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
13100 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
13110 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
13120 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
13130 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
13150 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13160 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
13170 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
13180 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13190 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
131a0 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  . If non-zero, t
131b0 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c  hen.** URI handl
131c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
131d0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
131e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
131f0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
13200 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61  ling.** is globa
13210 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66  lly disabled. If
13220 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13230 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
13240 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
13250 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
13260 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
13270 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
13280 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
13290 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
132a0 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
132b0 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
132c0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
132d0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
132e0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
132f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
13300 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
13310 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
13320 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
13330 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
13340 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74  is opened. If it
13350 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13360 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
13370 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
13380 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
13390 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
133a0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
133b0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
133c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133d0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42  ion is opened. B
133e0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
133f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
13400 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
13410 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
13420 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
13430 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
13440 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
13450 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
13460 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
13470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13480 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
13490 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
134a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
134b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
134c0 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f   <dd> This optio
134d0 6e 20 74 61 6b 73 20 61 20 73 69 6e 67 6c 65 20  n taks a single 
134e0 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74  integer argument
134f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
13500 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f  reted as.** a bo
13510 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
13520 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
13530 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
13540 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
13550 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c  for.** full tabl
13560 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
13570 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20  uery optimizer. 
13580 20 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74   The default set
13590 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
135a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
135b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
135c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
135d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
135e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
135f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
13600 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
13610 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
13620 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
13630 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
13640 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
13650 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
13660 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
13670 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
13680 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
13690 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
136a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
136b0 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20  .** malfunction 
136c0 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
136d0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
136e0 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
136f0 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
13700 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
13710 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
13720 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
13730 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
13740 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
13750 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
13760 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
13770 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
13780 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13790 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
137a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
137b0 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
137c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
137d0 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
137e0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
137f0 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
13800 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
13810 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
13820 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
13830 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
13840 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
13850 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
13860 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
13870 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
13880 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dl>.**.** [[S
13890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
138a0 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
138b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
138c0 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
138d0 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
138e0 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
138f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13900 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
13910 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72  ENABLE_SQLLOG pr
13920 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
13930 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
13940 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
13950 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
13960 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
13970 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
13980 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
13990 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
139a0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
139b0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
139c0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
139d0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
139e0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
139f0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
13a00 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
13a10 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
13a20 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
13a30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
13a40 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
13a50 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
13a60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
13a70 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
13a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
13a90 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
13aa0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13ab0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
13ac0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
13ad0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
13ae0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
13af0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
13b00 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
13b10 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
13b20 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
13b30 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
13b40 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
13b50 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
13b60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
13b70 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
13b80 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
13b90 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
13ba0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
13bb0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
13bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
13bd0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
13be0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13bf0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
13c00 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
13c10 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
13c20 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
13c30 20 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   case..** </dl>.
13c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13c50 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
13c60 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
13c70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13c80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13c90 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
13ca0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
13cb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13cc0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
13cd0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
13ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13cf0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
13d00 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13d10 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
13d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13d30 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
13d40 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
13d50 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
13d60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13d70 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
13d80 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
13d90 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
13da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13db0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
13dc0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
13dd0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
13de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13df0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
13e00 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
13e10 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
13e20 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
13e30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13e40 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
13e50 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
13e60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13e70 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
13e80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
13e90 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
13ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13eb0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
13ec0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
13ed0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
13ee0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
13ef0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
13f00 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
13f10 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
13f20 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
13f30 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
13f40 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
13f50 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
13f60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f70 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
13f80 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
13f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13fa0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
13fb0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
13fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13fd0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
13fe0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
13ff0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
14000 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14010 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
14020 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
14030 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14040 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
14050 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
14060 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
14070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14080 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14090 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
140a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
140b0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
140c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
140d0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
140e0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
140f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14100 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
14110 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
14120 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  , void* */../*.*
14130 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
14140 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
14150 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
14160 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
14170 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
14180 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
14190 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
141a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
141b0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
141c0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
141d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
141e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
141f0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
14200 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
14210 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
14220 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
14230 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
14240 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
14250 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
14260 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
14270 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
14280 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
14290 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
142a0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
142b0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
142c0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
142d0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
142e0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
142f0 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
14300 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14310 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
14320 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
14330 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
14340 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
14350 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
14360 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
14370 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
14380 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
14390 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
143a0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
143b0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
143c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
143d0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
143e0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
143f0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
14400 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
14410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
14420 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
14430 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
14440 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14450 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
14460 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
14470 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
14480 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14490 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
144a0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
144b0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
144c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
144d0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
144e0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
144f0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
14500 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
14510 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
14520 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
14530 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
14540 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
14550 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
14560 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
14570 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
14580 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14590 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
145a0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
145b0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
145c0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
145d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
145e0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
145f0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
14600 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
14610 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
14620 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
14630 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
14640 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
14650 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
14660 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
14670 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
14680 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14690 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
146a0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
146b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
146c0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
146d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
146e0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
146f0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
14700 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
14710 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
14720 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
14730 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
14740 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
14750 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
14760 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
14770 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14780 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
14790 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
147a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
147b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
147c0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
147d0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
147e0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
147f0 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
14800 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
14810 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
14820 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
14830 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14840 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
14850 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
14860 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
14870 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
14880 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
14890 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
148a0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
148b0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
148c0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
148d0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
148e0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
148f0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
14900 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
14910 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
14920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
14930 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
14940 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
14950 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
14960 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
14970 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
14980 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
14990 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
149a0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
149b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
149c0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
149d0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
149e0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
149f0 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
14a00 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
14a10 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
14a20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
14a30 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
14a40 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
14a50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
14a60 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
14a70 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
14a80 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
14a90 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
14aa0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
14ab0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
14ac0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
14ad0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
14ae0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
14af0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14b00 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
14b10 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
14b20 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
14b30 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
14b40 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
14b50 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
14b60 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
14b70 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
14b80 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
14b90 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
14ba0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
14bb0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
14bc0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
14bd0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
14be0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
14bf0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
14c00 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
14c10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14c20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
14c30 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
14c40 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
14c50 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
14c60 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
14c70 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
14c80 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
14c90 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
14ca0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14cb0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14cc0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
14cd0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
14ce0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
14cf0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
14d00 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
14d10 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
14d20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
14d30 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
14d40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
14d50 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
14d60 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
14d70 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
14d80 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
14d90 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
14da0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
14db0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
14dc0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14dd0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
14de0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
14df0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14e00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14e10 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
14e20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
14e30 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14e40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
14e50 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
14e60 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
14e70 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
14e80 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
14e90 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
14ea0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
14eb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
14ec0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
14ed0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
14ee0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14ef0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
14f00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
14f10 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
14f20 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
14f30 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
14f40 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
14f50 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
14f60 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
14f70 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
14f80 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
14f90 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
14fa0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
14fb0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
14fc0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
14fd0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
14fe0 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
14ff0 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
15000 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
15010 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
15020 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
15030 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
15040 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
15050 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
15060 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
15070 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
15080 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
15090 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
150a0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
150b0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
150c0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
150d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
150e0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
150f0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
15100 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
15110 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
15120 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
15130 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
15140 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
15150 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
15160 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
15170 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
15180 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
15190 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
151a0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
151b0 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
151c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
151d0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
151e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
151f0 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69  nt.  ^As of SQLi
15200 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
15210 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a  , this routines.
15220 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  ** records the l
15230 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
15240 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72   of both ordinar
15250 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69  y tables and [vi
15260 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a  rtual tables]..*
15270 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
15280 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
15290 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
152a0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
152b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
152c0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
152d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
152e0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
152f0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
15300 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
15310 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
15320 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
15330 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
15340 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
15350 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
15360 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
15370 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
15380 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
15390 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
153a0 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
153b0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
153c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
153d0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
153e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
153f0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
15400 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
15410 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
15420 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
15430 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
15440 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
15450 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
15460 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
15470 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
15480 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
15490 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
154a0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
154b0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
154c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
154d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
154e0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
154f0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
15500 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
15510 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
15520 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
15530 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
15540 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
15550 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
15560 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
15570 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
15580 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
15590 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
155a0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
155b0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
155c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
155d0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
155e0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
155f0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
15600 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
15610 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
15620 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
15630 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
15640 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
15650 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
15660 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
15670 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
15680 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
15690 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
156a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
156b0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
156c0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
156d0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
156e0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
156f0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
15700 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
15710 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
15720 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
15730 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
15740 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
15750 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
15760 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
15770 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
15780 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
15790 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
157a0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
157b0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
157c0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
157d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
157e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
157f0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
15800 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
15810 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
15820 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
15830 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
15840 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
15850 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
15860 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
15870 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
15880 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
15890 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
158a0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
158b0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
158c0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
158d0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
158e0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
158f0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
15900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15910 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
15920 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
15930 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
15940 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
15950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
15960 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
15970 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
15980 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
15990 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
159a0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
159b0 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
159c0 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
159d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
159e0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
159f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15a00 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
15a10 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
15a20 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
15a30 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
15a40 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
15a50 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
15a60 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
15a70 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
15a80 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
15a90 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
15aa0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
15ab0 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
15ac0 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
15ad0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
15ae0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
15af0 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
15b00 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
15b10 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
15b20 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
15b30 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
15b40 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
15b50 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
15b60 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
15b70 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
15b80 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
15b90 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
15ba0 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
15bb0 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
15bc0 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
15bd0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
15be0 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
15bf0 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
15c00 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
15c10 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
15c20 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
15c30 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
15c40 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
15c50 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
15c60 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
15c70 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
15c80 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
15c90 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
15ca0 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
15cb0 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
15cc0 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
15cd0 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
15ce0 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
15cf0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
15d00 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
15d10 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
15d20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
15d30 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
15d40 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
15d50 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
15d60 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
15d70 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
15d80 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
15d90 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
15da0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
15db0 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
15dc0 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
15dd0 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
15de0 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
15df0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
15e00 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
15e10 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
15e20 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
15e30 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
15e40 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
15e50 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
15e60 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
15e70 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
15e80 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
15e90 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
15ea0 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
15eb0 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
15ec0 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
15ed0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
15ee0 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
15ef0 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
15f00 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
15f10 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
15f20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
15f30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
15f40 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
15f50 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
15f60 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
15f70 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
15f80 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
15f90 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
15fa0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
15fb0 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
15fc0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
15fd0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
15fe0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
15ff0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
16000 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
16010 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
16020 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16030 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
16040 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
16050 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
16060 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
16070 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
16080 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
16090 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
160a0 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
160b0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
160c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
160d0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
160e0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
160f0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
16100 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
16110 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
16120 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
16130 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
16140 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
16150 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
16160 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
16170 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
16180 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
16190 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
161a0 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
161b0 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
161c0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
161d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
161e0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
161f0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
16200 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
16210 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
16220 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
16230 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
16240 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
16250 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
16260 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
16270 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
16280 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
16290 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
162a0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
162b0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
162c0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
162d0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
162e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
162f0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
16300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16310 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
16320 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
16330 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
16340 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
16350 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
16360 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
16370 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
16380 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
16390 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
163a0 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
163b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
163c0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
163d0 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
163e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
163f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
16400 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
16410 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
16420 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
16430 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
16440 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
16450 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
16460 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
16470 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
16480 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
16490 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
164a0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
164b0 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
164c0 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
164d0 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
164e0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
164f0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
16500 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
16510 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
16520 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
16530 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
16540 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
16550 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
16560 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
16570 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
16580 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
16590 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
165a0 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
165b0 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
165c0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
165d0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
165e0 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
165f0 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
16600 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
16610 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
16620 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
16630 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
16640 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
16650 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
16660 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
16670 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
16680 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
16690 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
166a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
166b0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
166c0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
166d0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
166e0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
166f0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
16700 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
16710 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
16720 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
16730 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
16740 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
16750 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
16760 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
16770 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
16780 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
16790 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
167a0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
167b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
167c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
167d0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
167e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
167f0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
16800 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
16810 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
16820 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
16830 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
16840 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
16850 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
16860 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
16870 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
16880 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
16890 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
168a0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
168b0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
168c0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
168d0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
168e0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
168f0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
16900 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
16910 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
16920 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
16930 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
16940 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
16950 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
16960 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
16970 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
16980 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
16990 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
169a0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
169b0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
169c0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
169d0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
169e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
169f0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
16a00 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
16a10 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
16a20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16a30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
16a40 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
16a50 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
16a60 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
16a70 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
16a80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
16a90 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
16aa0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
16ab0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
16ac0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
16ad0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
16ae0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
16af0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
16b00 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
16b10 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
16b20 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
16b30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
16b40 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
16b50 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
16b60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
16b70 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
16b80 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
16b90 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
16ba0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
16bb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
16bc0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
16bd0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
16be0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
16bf0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
16c00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
16c10 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
16c20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
16c30 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
16c40 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
16c50 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
16c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16c70 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
16c80 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
16c90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
16ca0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
16cb0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
16cc0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
16cd0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
16ce0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
16cf0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
16d00 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
16d10 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
16d20 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
16d30 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
16d40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16d50 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
16d60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
16d70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
16d80 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
16d90 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
16da0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
16db0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
16dc0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
16dd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
16de0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
16df0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16e00 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
16e10 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
16e20 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
16e30 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
16e40 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
16e50 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
16e60 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
16e70 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
16e80 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
16e90 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
16ea0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
16eb0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
16ec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
16ed0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
16ee0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
16ef0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
16f00 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
16f10 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
16f20 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
16f30 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
16f40 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
16f50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
16f60 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
16f70 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
16f80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
16f90 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
16fa0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
16fb0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
16fc0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
16fd0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
16fe0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
16ff0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
17000 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17010 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
17020 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
17030 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
17040 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
17050 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
17060 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
17070 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
17080 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
17090 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
170a0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
170b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
170c0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
170d0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
170e0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
170f0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
17100 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
17110 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
17120 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
17130 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
17140 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
17150 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
17160 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
17170 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
17180 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
17190 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
171a0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
171b0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
171c0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
171d0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
171e0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
171f0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
17200 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
17210 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
17220 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
17230 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
17240 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
17250 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
17260 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
17270 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
17280 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
17290 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
172a0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
172b0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
172c0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
172d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
172e0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
172f0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
17300 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
17310 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
17320 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
17330 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
17340 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
17350 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
17360 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
17370 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
17380 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
17390 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
173a0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
173b0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
173c0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
173d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
173e0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
173f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
17400 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
17410 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
17420 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
17430 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
17440 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
17450 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
17460 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
17470 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
17480 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
17490 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
174a0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
174b0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
174c0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
174d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
174e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
174f0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
17500 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
17510 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
17520 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
17530 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
17540 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
17550 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
17560 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
17570 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
17580 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
17590 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
175a0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
175b0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
175c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
175d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
175e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
175f0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
17600 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
17610 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
17620 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
17630 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
17640 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17650 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
17660 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
17670 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
17680 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
17690 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
176a0 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
176b0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
176c0 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
176d0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
176e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
176f0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
17700 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
17710 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
17720 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
17730 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
17740 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
17750 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
17760 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
17770 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
17780 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
17790 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
177a0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
177b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
177c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
177d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
177e0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
177f0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
17800 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
17810 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
17820 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
17830 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
17840 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17850 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
17860 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
17870 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
17880 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
17890 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
178a0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
178b0 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
178c0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
178d0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
178e0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
178f0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
17900 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
17910 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
17920 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
17930 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
17940 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
17950 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
17960 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
17970 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17980 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
17990 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
179a0 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
179b0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
179c0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
179d0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
179e0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
179f0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
17a00 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
17a10 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
17a20 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
17a30 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
17a40 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
17a50 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
17a60 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
17a70 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
17a80 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
17a90 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
17aa0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
17ab0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
17ac0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
17ad0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
17ae0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
17af0 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
17b00 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
17b10 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
17b20 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
17b30 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
17b40 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
17b50 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
17b60 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
17b70 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
17b80 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
17b90 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
17ba0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
17bb0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
17bc0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
17bd0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
17be0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
17bf0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
17c00 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
17c10 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
17c20 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
17c30 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
17c40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
17c50 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
17c60 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
17c70 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
17c80 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
17c90 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
17ca0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
17cb0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
17cc0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
17cd0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
17ce0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
17cf0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17d00 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
17d10 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
17d20 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
17d30 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
17d40 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
17d50 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
17d60 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
17d70 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
17d80 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
17d90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
17da0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
17db0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
17dc0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
17dd0 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
17de0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
17df0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17e00 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
17e10 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
17e20 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
17e30 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
17e40 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
17e50 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
17e60 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
17e70 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
17e80 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
17e90 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
17ea0 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
17eb0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
17ec0 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
17ed0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
17ee0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
17ef0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
17f00 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
17f10 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
17f20 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
17f30 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
17f40 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
17f50 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
17f60 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
17f70 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
17f80 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
17f90 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
17fa0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
17fb0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
17fc0 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
17fd0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
17fe0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
17ff0 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
18000 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
18010 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
18020 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18030 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
18040 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
18050 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
18060 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
18070 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
18080 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
18090 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
180a0 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
180b0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
180c0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
180d0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
180e0 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
180f0 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
18100 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
18110 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
18120 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
18130 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
18140 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
18150 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
18160 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
18170 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
18180 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
18190 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
181a0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
181b0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
181c0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
181d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
181e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
181f0 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
18200 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
18210 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
18220 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
18230 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
18240 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
18250 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
18260 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
18270 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
18280 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
18290 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
182a0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
182b0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
182c0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
182d0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
182e0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
182f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18300 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
18310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18320 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18330 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18340 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
18350 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
18360 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
18370 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
18380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18390 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
183a0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
183b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
183c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
183d0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
183e0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
183f0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
18400 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
18410 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
18420 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
18430 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
18440 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
18450 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
18460 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
18470 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
18480 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
18490 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
184a0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
184b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
184c0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
184d0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
184e0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
184f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18500 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
18510 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
18520 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
18530 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
18540 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
18550 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
18560 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
18570 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
18580 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
18590 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
185a0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
185b0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
185c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
185d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
185e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
185f0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
18600 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
18610 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
18620 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
18630 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
18640 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18650 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
18660 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
18670 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
18680 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
18690 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
186a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
186b0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
186c0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
186d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
186e0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
186f0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
18700 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
18710 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
18720 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
18730 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
18740 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
18750 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
18760 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
18770 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
18780 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
18790 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
187a0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
187b0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
187c0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
187d0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
187e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
187f0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
18800 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
18810 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
18820 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
18830 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
18840 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
18850 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
18860 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
18870 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
18880 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
18890 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
188a0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
188b0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
188c0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
188d0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
188e0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
188f0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
18900 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
18910 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
18920 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
18930 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
18940 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
18950 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
18960 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
18970 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
18980 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
18990 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
189a0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
189b0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
189c0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
189d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
189e0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
189f0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
18a00 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
18a10 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
18a20 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
18a30 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
18a40 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
18a50 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
18a60 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
18a70 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
18a80 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
18a90 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
18aa0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
18ab0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
18ac0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
18ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
18ae0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
18af0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
18b00 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
18b10 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
18b20 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
18b30 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
18b40 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
18b50 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
18b60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
18b70 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
18b80 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
18b90 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
18ba0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
18bb0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
18bc0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
18bd0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
18be0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
18bf0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
18c00 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
18c10 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18c20 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
18c30 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
18c40 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
18c50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18c60 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
18c70 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
18c80 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
18c90 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
18ca0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
18cb0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
18cc0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18cd0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
18ce0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
18cf0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
18d00 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
18d10 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
18d20 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
18d30 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
18d40 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
18d50 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
18d60 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
18d70 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
18d80 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
18d90 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
18da0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18db0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
18dc0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
18dd0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
18de0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
18df0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
18e00 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
18e10 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
18e20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18e30 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
18e40 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18e50 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
18e60 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18e70 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
18e80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
18e90 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
18ea0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
18eb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
18ec0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
18ed0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
18ee0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
18ef0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
18f00 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
18f10 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
18f20 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
18f30 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
18f40 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
18f50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
18f60 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
18f70 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
18f80 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
18f90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
18fa0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
18fb0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
18fc0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
18fd0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
18fe0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
18ff0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
19000 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
19010 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
19020 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
19030 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
19040 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
19050 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
19060 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
19070 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
19080 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
19090 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
190a0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
190b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
190c0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
190d0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
190e0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
190f0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
19100 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
19110 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
19120 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
19130 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
19140 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
19150 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
19160 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
19170 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
19180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19190 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
191a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
191b0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
191c0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
191d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
191e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
191f0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
19200 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
19210 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
19220 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
19230 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
19240 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
19250 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
19260 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
19270 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
19280 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
19290 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
192a0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
192b0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
192c0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
192d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
192e0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
192f0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
19300 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
19310 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
19320 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
19330 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
19340 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
19350 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
19360 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
19370 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
19380 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
19390 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
193a0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
193b0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
193c0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
193d0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
193e0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
193f0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
19400 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
19410 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
19420 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
19430 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
19440 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
19450 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
19460 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
19470 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
19480 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
19490 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
194a0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
194b0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
194c0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
194d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
194e0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
194f0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
19500 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
19510 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19520 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
19530 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
19540 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
19550 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
19560 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
19570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19580 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
19590 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
195a0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
195b0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
195c0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
195d0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
195e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
195f0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
19600 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
19610 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
19620 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
19630 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
19640 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
19650 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
19660 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
19670 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
19680 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
19690 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
196a0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
196b0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
196c0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
196d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
196e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
196f0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
19700 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
19710 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
19720 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
19730 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
19740 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
19750 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
19760 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
19770 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
19780 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
19790 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
197a0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
197b0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
197c0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
197d0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
197e0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
197f0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
19800 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
19810 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
19820 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
19830 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
19840 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
19850 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
19860 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
19870 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
19880 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
19890 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
198a0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
198b0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
198c0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
198d0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
198e0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
198f0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
19900 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
19910 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
19920 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
19930 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
19940 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
19950 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
19960 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
19970 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
19980 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
19990 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
199a0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
199b0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
199c0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
199d0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
199e0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
199f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19a00 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
19a10 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
19a20 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
19a30 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
19a40 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
19a50 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
19a60 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
19a70 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
19a80 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
19a90 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
19aa0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
19ab0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
19ac0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
19ad0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
19ae0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
19af0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
19b00 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
19b10 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
19b20 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
19b30 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
19b40 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
19b50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
19b60 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
19b70 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
19b80 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
19b90 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
19ba0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
19bb0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
19bc0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
19bd0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
19be0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
19bf0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
19c00 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
19c10 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
19c20 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
19c30 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
19c40 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
19c50 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
19c60 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
19c70 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
19c80 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
19c90 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
19ca0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
19cb0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
19cc0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
19cd0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
19ce0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
19cf0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
19d00 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
19d10 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
19d20 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
19d30 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
19d40 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
19d50 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
19d60 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
19d70 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
19d80 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
19d90 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
19da0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
19db0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
19dc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
19dd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
19de0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
19df0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
19e00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19e10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
19e20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
19e30 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
19e40 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
19e50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19e60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
19e70 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
19e80 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
19e90 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
19ea0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
19eb0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
19ec0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
19ed0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
19ee0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
19ef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19f00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
19f10 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
19f20 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
19f30 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
19f40 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
19f50 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
19f60 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
19f70 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
19f80 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
19f90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19fa0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
19fb0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
19fc0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
19fd0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19fe0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
19ff0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1a000 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1a010 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1a020 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1a030 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1a040 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1a050 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a060 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1a070 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1a080 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1a090 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1a0a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a0b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1a0c0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1a0d0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1a0e0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1a0f0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1a100 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1a110 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1a120 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1a130 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1a140 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1a150 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1a160 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1a170 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1a180 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1a190 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1a1a0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1a1b0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1a1c0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1a1d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1a1e0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1a1f0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1a200 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1a210 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1a220 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1a230 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1a240 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1a250 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1a260 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1a270 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a280 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1a290 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1a2a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a2b0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1a2c0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1a2d0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1a2e0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1a2f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1a300 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1a310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a320 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1a330 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1a340 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1a350 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1a360 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1a370 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1a380 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1a390 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1a3a0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1a3b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1a3c0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1a3d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1a3e0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1a3f0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1a400 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1a410 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1a420 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1a430 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1a440 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1a450 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1a460 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1a470 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1a480 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1a490 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1a4a0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1a4b0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1a4c0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1a4d0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a4e0 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1a4f0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1a500 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1a510 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1a520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a530 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1a540 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1a550 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1a560 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1a570 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1a580 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1a590 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1a5a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1a5b0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1a5c0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1a5d0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1a5e0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1a5f0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1a600 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1a610 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1a620 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1a630 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1a640 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1a650 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1a660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1a680 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1a690 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1a6a0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1a6b0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1a6c0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1a6d0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1a6e0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1a6f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1a700 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1a710 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1a720 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1a730 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1a740 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1a750 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1a760 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1a770 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1a780 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1a790 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1a7a0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1a7b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
1a7c0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1a7d0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1a7e0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1a7f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1a800 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1a810 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1a820 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1a830 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1a840 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1a850 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1a860 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1a870 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1a880 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1a890 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1a8a0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1a8b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1a8c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1a8d0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1a8e0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1a8f0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1a900 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1a910 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1a920 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1a930 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1a940 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1a950 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1a960 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1a970 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1a980 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1a990 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1a9a0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1a9b0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1a9c0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1a9d0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1a9e0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1a9f0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1aa00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1aa10 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1aa20 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1aa30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1aa40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1aa50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1aa60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1aa70 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1aa80 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1aa90 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1aaa0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1aab0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1aac0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1aad0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1aae0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1aaf0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1ab00 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1ab10 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1ab20 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1ab30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ab40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1ab50 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1ab60 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1ab70 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1ab80 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1ab90 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1aba0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1abb0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1abc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1abd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1abe0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1abf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1ac00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ac10 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1ac20 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1ac30 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1ac40 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1ac50 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1ac60 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1ac70 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1ac80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ac90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1aca0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1acb0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1acc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1acd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1ace0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1acf0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1ad00 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1ad10 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1ad20 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1ad30 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1ad40 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1ad50 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1ad60 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1ad70 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1ad80 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1ad90 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1ada0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1adb0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1adc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1add0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1ade0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1adf0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1ae00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1ae10 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1ae20 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ae30 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1ae40 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1ae50 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1ae60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1ae70 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1ae80 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1ae90 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1aea0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1aeb0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1aec0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1aed0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1aee0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1aef0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1af00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1af10 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1af20 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1af30 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1af40 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1af50 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1af60 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1af70 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1af80 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1af90 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1afa0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1afb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1afc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1afd0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1afe0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1aff0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1b000 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1b010 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1b020 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1b030 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1b040 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1b050 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1b060 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1b070 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1b080 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1b090 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1b0a0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1b0b0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1b0c0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1b0d0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1b0e0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1b0f0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1b100 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1b110 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1b120 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1b130 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1b140 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1b150 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1b160 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1b170 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1b180 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1b190 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1b1a0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1b1b0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1b1c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1b1d0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1b1e0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1b1f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1b200 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1b210 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1b220 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1b230 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1b240 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1b250 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1b260 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1b270 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b280 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1b290 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1b2a0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1b2b0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1b2c0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1b2d0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1b2e0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1b2f0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1b300 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1b310 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1b320 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1b330 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1b340 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1b350 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
1b360 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1b370 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
1b380 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1b390 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1b3a0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1b3b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b3c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1b3d0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1b3e0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1b3f0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1b400 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1b410 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1b420 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1b430 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b440 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1b450 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1b460 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1b470 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1b480 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1b490 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1b4a0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1b4b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1b4c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1b4d0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1b4e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b4f0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1b500 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1b510 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1b520 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1b530 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1b540 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1b550 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1b560 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1b570 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1b580 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1b590 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1b5a0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1b5b0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1b5c0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1b5d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1b5e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1b5f0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1b600 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1b610 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1b620 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1b630 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1b640 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1b650 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1b660 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1b670 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1b680 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1b690 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1b6a0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1b6b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1b6c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b6d0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1b6e0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1b6f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1b700 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1b710 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1b720 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1b730 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1b740 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1b750 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1b760 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1b770 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1b780 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1b790 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1b7a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1b7b0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1b7c0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1b7d0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1b7e0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1b7f0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1b800 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1b810 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1b820 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1b830 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1b840 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1b850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1b860 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1b870 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1b880 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1b890 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1b8a0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1b8b0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1b8c0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1b8d0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1b8e0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1b8f0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1b900 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1b910 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1b920 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1b930 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1b940 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1b950 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1b960 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1b970 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1b980 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1b990 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1b9a0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1b9b0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1b9c0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1b9d0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1b9e0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1b9f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1ba00 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1ba10 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1ba20 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1ba30 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1ba40 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
1ba50 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
1ba60 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
1ba70 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
1ba80 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
1ba90 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
1baa0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
1bab0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1bac0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
1bad0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1bae0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
1baf0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1bb00 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
1bb10 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
1bb20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
1bb30 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
1bb40 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
1bb50 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
1bb60 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
1bb70 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
1bb80 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
1bb90 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
1bba0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1bbb0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1bbc0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1bbd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1bbe0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1bbf0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1bc00 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1bc10 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1bc20 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1bc30 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1bc40 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1bc50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bc60 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1bc70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1bc80 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1bc90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1bca0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1bcb0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1bcc0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1bcd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1bce0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1bcf0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1bd00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1bd10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1bd20 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1bd30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1bd40 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1bd50 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1bd60 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1bd70 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1bd80 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1bd90 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1bda0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1bdb0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1bdc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1bdd0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1bde0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1bdf0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1be00 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1be10 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1be20 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1be30 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1be40 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1be50 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1be60 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1be70 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1be80 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1be90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1bea0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1beb0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1bec0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1bed0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1bee0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1bef0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1bf00 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1bf10 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1bf20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1bf30 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1bf40 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1bf50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1bf60 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1bf70 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1bf80 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1bf90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1bfa0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1bfb0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1bfc0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1bfd0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1bfe0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1bff0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1c000 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c010 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1c020 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1c030 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1c040 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1c050 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1c060 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1c070 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1c080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c090 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1c0a0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1c0b0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1c0c0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1c0d0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1c0e0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1c0f0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1c100 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1c110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1c120 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1c130 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c140 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1c150 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1c160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c170 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1c180 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1c190 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1c1a0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1c1b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1c1c0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1c1d0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1c1e0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1c1f0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1c200 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1c210 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1c220 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1c230 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1c240 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1c250 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1c260 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1c270 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1c280 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1c290 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1c2a0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1c2b0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1c2c0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1c2d0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1c2e0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1c2f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c300 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1c310 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1c320 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c330 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1c340 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1c350 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1c360 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1c370 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1c380 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1c390 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1c3a0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1c3b0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1c3c0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1c3d0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1c3e0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1c3f0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1c400 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1c410 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1c420 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1c430 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1c440 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1c450 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1c460 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1c470 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1c480 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1c490 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1c4a0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1c4b0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1c4c0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1c4d0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1c4e0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1c4f0 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1c500 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1c510 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1c520 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1c530 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1c540 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1c550 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1c560 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1c570 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1c580 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1c590 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1c5a0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1c5b0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1c5c0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1c5d0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1c5e0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1c5f0 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1c600 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1c610 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1c620 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1c630 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1c640 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1c650 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1c660 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1c670 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1c680 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1c690 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1c6a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1c6b0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1c6c0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1c6d0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1c6e0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1c6f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1c700 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1c710 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1c720 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1c730 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1c740 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1c750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1c760 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1c770 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1c780 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1c790 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1c7a0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1c7b0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1c7c0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1c7d0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1c7e0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1c7f0 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1c800 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1c810 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1c820 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1c830 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1c840 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1c850 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1c860 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1c870 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1c880 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1c890 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1c8a0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1c8b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1c8c0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1c8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c8e0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1c8f0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1c900 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1c910 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1c920 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1c930 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1c940 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1c950 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1c960 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1c970 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1c980 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1c990 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1c9a0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1c9b0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1c9c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1c9d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1c9e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c9f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1ca00 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1ca10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1ca20 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1ca30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ca40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ca50 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1ca60 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1ca70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ca80 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1ca90 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1caa0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1cab0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1cac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1cad0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1cae0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1caf0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1cb00 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1cb10 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1cb20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cb30 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1cb40 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1cb50 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1cb60 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1cb70 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1cb80 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1cb90 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1cba0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1cbb0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1cbc0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1cbd0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1cbe0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cbf0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1cc00 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1cc10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1cc20 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1cc30 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1cc40 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1cc50 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1cc60 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1cc70 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1cc80 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1cc90 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1cca0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1ccb0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1ccc0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1ccd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1cce0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1ccf0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1cd00 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1cd10 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
1cd20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1cd30 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1cd40 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1cd50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1cd60 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1cd70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1cd80 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1cd90 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1cda0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cdb0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1cdc0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1cdd0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1cde0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1cdf0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ce00 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1ce10 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1ce20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1ce30 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1ce40 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1ce50 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1ce60 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1ce70 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1ce80 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1ce90 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1cea0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1ceb0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1cec0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1ced0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1cee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1cef0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1cf00 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1cf10 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53  lso used as a [S
1cf20 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
1cf30 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a   return code].**
1cf40 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1cf50 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1cf60 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1cf70 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1cf80 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1cf90 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1cfa0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1cfb0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1cfc0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1cfd0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1cfe0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1cff0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1d000 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1d010 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1d020 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1d030 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1d040 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1d050 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1d060 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1d070 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1d080 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1d090 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1d0a0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1d0b0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1d0c0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1d0d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1d0e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1d0f0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1d100 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1d110 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1d120 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1d130 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1d140 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1d150 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1d160 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d170 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1d180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1d190 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1d1a0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1d1b0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1d1c0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1d1d0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1d1e0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1d1f0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1d200 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1d210 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1d220 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1d230 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1d240 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1d250 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1d260 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1d270 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1d280 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1d290 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1d2a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d2b0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1d2c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1d2d0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1d2e0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1d2f0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1d300 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1d310 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d320 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1d330 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1d340 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1d350 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1d360 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1d370 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1d380 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1d390 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1d3a0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1d3b0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1d3c0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1d3d0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1d3e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d3f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1d400 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1d410 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1d420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d430 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1d440 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1d450 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1d460 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1d470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d480 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1d490 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1d4a0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d4b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d4c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d4d0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1d4e0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1d4f0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1d500 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d510 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d520 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1d530 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1d540 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1d550 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d560 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1d570 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1d580 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1d590 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1d5a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1d5b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1d5c0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1d5d0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1d5e0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1d5f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d600 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d610 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1d620 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1d630 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1d640 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d650 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1d660 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1d670 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1d680 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1d690 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d6a0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1d6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1d6c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1d6d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d6e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d6f0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1d700 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1d710 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1d720 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d730 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d740 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1d750 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1d760 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1d770 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d780 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d790 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1d7a0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1d7b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1d7c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d7d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d7e0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1d7f0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1d800 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d810 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d820 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d830 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1d840 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1d850 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1d860 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1d870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d880 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1d890 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1d8a0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1d8b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d8c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d8d0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1d8e0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1d8f0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1d900 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d920 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1d930 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1d940 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1d950 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1d970 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1d980 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1d990 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d9a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1d9c0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1d9d0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1d9e0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1d9f0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1da00 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1da10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1da20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1da30 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1da40 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1da50 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1da60 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1da70 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1da80 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1da90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1daa0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1dab0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1dac0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1dad0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1dae0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1daf0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1db00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1db10 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1db20 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1db30 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1db40 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1db50 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1db60 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1db70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1db80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1db90 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1dba0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1dbb0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1dbc0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1dbd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1dbe0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1dbf0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1dc00 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1dc10 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1dc20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dc30 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1dc40 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1dc50 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1dc60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dc70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dc80 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1dc90 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1dca0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dcb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1dcc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dcd0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1dce0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1dcf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dd00 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1dd10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dd20 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1dd30 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1dd40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1dd50 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1dd60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dd70 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1dd80 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1dd90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1dda0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1ddb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ddc0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1ddd0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1dde0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1ddf0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1de00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1de10 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1de20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1de30 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
1de40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1de50 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1de60 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1de70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1de80 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1de90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1dea0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1deb0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1dec0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1ded0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1dee0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1def0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1df00 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1df10 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1df20 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1df30 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1df40 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1df50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1df60 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1df70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1df80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1df90 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1dfa0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1dfb0 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1dfc0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1dfd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1dfe0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1dff0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1e000 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1e010 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1e020 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1e030 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1e040 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1e050 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1e060 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1e070 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1e080 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1e090 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1e0a0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1e0b0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1e0c0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
1e0d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e0e0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1e0f0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1e100 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1e110 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1e120 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1e130 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1e140 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1e150 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1e160 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1e170 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1e180 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1e190 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1e1a0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1e1b0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
1e1c0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1e1d0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
1e1e0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
1e1f0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
1e200 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
1e210 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
1e220 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
1e230 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
1e240 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
1e250 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
1e260 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
1e270 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
1e280 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
1e290 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1e2a0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
1e2b0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
1e2c0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
1e2d0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
1e2e0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
1e2f0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1e300 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
1e310 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
1e320 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
1e330 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1e340 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
1e350 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
1e360 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
1e370 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
1e380 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
1e390 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
1e3a0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
1e3b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1e3c0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1e3d0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1e3e0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1e3f0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1e400 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1e410 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1e420 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1e430 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1e440 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1e450 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1e460 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1e470 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1e480 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1e490 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1e4a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1e4b0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1e4c0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1e4d0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1e4e0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1e4f0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1e500 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1e510 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1e520 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e530 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1e540 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1e550 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1e560 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1e570 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1e580 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1e590 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1e5a0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1e5b0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1e5c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1e5d0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1e5e0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1e5f0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1e600 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1e610 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1e620 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1e630 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1e640 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1e650 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1e660 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1e670 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
1e680 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
1e690 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
1e6a0 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
1e6b0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
1e6c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e6d0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
1e6e0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
1e6f0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
1e700 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
1e710 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
1e720 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
1e730 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
1e740 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
1e750 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1e760 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
1e770 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
1e780 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
1e790 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
1e7a0 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
1e7b0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1e7c0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1e7d0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1e7e0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1e7f0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1e800 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1e810 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1e820 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1e830 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1e840 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1e850 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1e860 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1e870 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1e880 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1e890 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1e8a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1e8b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1e8c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1e8d0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1e8e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e8f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e900 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1e910 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1e920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e930 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1e940 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1e950 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1e960 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
1e970 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1e980 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1e990 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
1e9a0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
1e9b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
1e9c0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
1e9d0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
1e9e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1e9f0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
1ea00 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
1ea10 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
1ea20 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
1ea30 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
1ea40 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1ea50 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1ea60 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
1ea70 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1ea80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1ea90 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
1eaa0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1eab0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
1eac0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
1ead0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
1eae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1eaf0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
1eb00 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
1eb10 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
1eb20 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1eb30 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
1eb40 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
1eb50 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
1eb60 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1eb70 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
1eb80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1eb90 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1eba0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1ebb0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1ebc0 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1ebd0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1ebe0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
1ebf0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
1ec00 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
1ec10 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
1ec20 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
1ec30 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
1ec40 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
1ec50 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1ec60 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1ec70 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
1ec80 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1ec90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1eca0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
1ecb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1ecc0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
1ecd0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
1ece0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
1ecf0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
1ed00 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
1ed10 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
1ed20 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
1ed30 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
1ed40 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
1ed50 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
1ed60 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
1ed70 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
1ed80 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1ed90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
1eda0 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
1edb0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1edc0 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
1edd0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
1ede0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
1edf0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
1ee00 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
1ee10 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
1ee20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
1ee30 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1ee40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ee50 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
1ee60 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
1ee70 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
1ee80 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
1ee90 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
1eea0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
1eeb0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1eec0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eed0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
1eee0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
1eef0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
1ef00 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
1ef10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
1ef20 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
1ef30 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
1ef40 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
1ef50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ef60 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
1ef70 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
1ef80 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
1ef90 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
1efa0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
1efb0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
1efc0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
1efd0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
1efe0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
1eff0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
1f000 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1f010 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1f020 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
1f030 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f040 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
1f050 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1f060 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
1f070 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
1f080 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1f090 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
1f0a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1f0b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
1f0c0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
1f0d0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
1f0e0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
1f0f0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
1f100 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1f110 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1f120 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1f130 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
1f140 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1f150 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1f160 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1f170 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1f180 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
1f190 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
1f1a0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1f1b0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1f1c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1f1d0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
1f1e0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
1f1f0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
1f200 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
1f210 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1f220 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1f230 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1f240 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1f250 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
1f260 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
1f270 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1f280 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1f290 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1f2a0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
1f2b0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
1f2c0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
1f2d0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
1f2e0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
1f2f0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
1f300 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1f310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1f320 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
1f330 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1f340 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1f350 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1f360 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1f370 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1f380 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1f390 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
1f3a0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1f3b0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
1f3c0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
1f3d0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
1f3e0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
1f3f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1f400 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
1f410 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1f420 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1f430 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1f440 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f450 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1f460 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1f470 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1f480 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1f490 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1f4a0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1f4b0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1f4c0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1f4d0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
1f4e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1f4f0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1f500 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
1f510 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f520 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
1f530 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1f540 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1f550 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
1f560 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
1f570 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
1f580 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
1f590 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1f5a0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1f5b0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1f5c0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1f5d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f5e0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
1f5f0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
1f600 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1f610 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
1f620 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1f630 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1f640 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
1f650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1f660 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1f670 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
1f680 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1f690 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
1f6a0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1f6b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
1f6c0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
1f6d0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
1f6e0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
1f6f0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
1f700 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
1f710 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1f720 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f730 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1f740 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f750 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
1f760 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
1f770 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1f780 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
1f790 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1f7a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
1f7b0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
1f7c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f7d0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
1f7e0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
1f7f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1f800 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
1f810 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
1f820 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1f830 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
1f840 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1f850 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
1f860 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
1f870 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1f880 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
1f890 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
1f8a0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
1f8b0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
1f8c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f8d0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
1f8e0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1f8f0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
1f900 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
1f910 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
1f920 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
1f930 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
1f940 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
1f950 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1f960 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
1f970 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
1f980 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
1f990 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
1f9a0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
1f9b0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
1f9c0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
1f9d0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
1f9e0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
1f9f0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
1fa00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1fa10 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
1fa20 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
1fa30 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
1fa40 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
1fa50 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
1fa60 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
1fa70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
1fa80 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
1fa90 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
1faa0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
1fab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fac0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1fad0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
1fae0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
1faf0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
1fb00 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
1fb10 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
1fb20 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
1fb30 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
1fb40 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
1fb50 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1fb60 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
1fb70 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
1fb80 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
1fb90 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
1fba0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
1fbb0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
1fbc0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
1fbd0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1fbe0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
1fbf0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
1fc00 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1fc10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
1fc20 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
1fc30 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
1fc40 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
1fc50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1fc60 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
1fc70 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fc80 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
1fc90 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
1fca0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
1fcb0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1fcc0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
1fcd0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
1fce0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
1fcf0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1fd00 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
1fd10 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
1fd20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
1fd30 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
1fd40 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
1fd50 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
1fd60 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
1fd70 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
1fd80 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
1fd90 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1fda0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
1fdb0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
1fdc0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
1fdd0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
1fde0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
1fdf0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
1fe00 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
1fe10 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
1fe20 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
1fe30 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
1fe40 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
1fe50 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
1fe60 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1fe70 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
1fe80 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
1fe90 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
1fea0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
1feb0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
1fec0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
1fed0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
1fee0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
1fef0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
1ff00 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
1ff10 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
1ff20 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
1ff30 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
1ff40 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
1ff50 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
1ff60 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
1ff70 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
1ff80 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
1ff90 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
1ffa0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
1ffb0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
1ffc0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
1ffd0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
1ffe0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
1fff0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
20000 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
20010 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
20020 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
20030 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
20040 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
20050 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
20060 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
20070 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
20080 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
20090 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
200a0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a   (e.g. "C:")..**
200b0 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
200c0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
200d0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
200e0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
200f0 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
20100 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
20110 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
20120 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
20130 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
20140 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
20150 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20160 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  on]..** SQLite i
20170 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f  nterprets the fo
20180 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75  llowing three qu
20190 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
201a0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
201b0 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
201c0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
201d0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
201e0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
201f0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
20200 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
20210 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
20220 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
20230 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
20240 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
20250 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
20260 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
20270 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
20280 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
20290 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
202a0 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
202b0 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
202c0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
202d0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
202e0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
202f0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
20300 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20310 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
20320 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
20330 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
20340 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
20350 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
20360 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
20370 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
20380 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
20390 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
203a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
203b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
203c0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
203d0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
203e0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
203f0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
20400 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
20410 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
20420 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
20430 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
20440 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
20450 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
20460 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
20470 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
20480 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
20490 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
204a0 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
204b0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
204c0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
204d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
204e0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
204f0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
20500 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
20510 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
20520 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
20530 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
20540 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
20550 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
20560 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20570 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
20580 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
20590 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
205a0 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
205b0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
205c0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
205d0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
205e0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
205f0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
20600 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
20610 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
20620 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
20630 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
20640 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
20650 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
20660 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
20670 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
20680 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
20690 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
206a0 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
206b0 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
206c0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
206d0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
206e0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
206f0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
20700 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
20710 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
20720 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
20730 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
20740 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
20750 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
20760 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
20770 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
20780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
20790 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
207a0 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
207b0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
207c0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
207d0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
207e0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
207f0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
20800 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
20810 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
20820 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
20830 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
20840 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
20850 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
20860 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
20870 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
20880 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
20890 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
208a0 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
208b0 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
208c0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
208d0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
208e0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
208f0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
20900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20910 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
20920 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
20930 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
20940 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
20950 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
20960 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
20970 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 65  haviour requeste
20980 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
20990 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
209a0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
209b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
209c0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
209d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
209e0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
209f0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
20a00 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
20a10 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
20a20 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
20a30 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
20a40 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
20a50 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
20a60 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
20a70 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
20a80 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
20a90 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
20aa0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
20ab0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
20ac0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
20ad0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
20ae0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
20af0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
20b00 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
20b10 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
20b20 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
20b30 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
20b40 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
20b50 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
20b60 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
20b70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
20b80 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
20b90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
20ba0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
20bb0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
20bc0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
20bd0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
20be0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
20bf0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
20c00 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
20c10 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
20c20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
20c30 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
20c40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
20c50 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
20c60 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
20c70 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
20c80 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20c90 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
20ca0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
20cb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20cc0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
20cd0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
20ce0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
20cf0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
20d00 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
20d10 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
20d20 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
20d30 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
20d40 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
20d50 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
20d60 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
20d70 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
20d80 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
20d90 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
20da0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
20db0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
20dc0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
20dd0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
20de0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
20df0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
20e00 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
20e10 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
20e20 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
20e30 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
20e40 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
20e50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
20e60 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
20e70 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
20e80 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
20e90 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
20ea0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
20eb0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
20ec0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
20ed0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
20ee0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
20ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
20f00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
20f10 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
20f20 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
20f30 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
20f40 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
20f50 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
20f60 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
20f70 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
20f80 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
20f90 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20  -nolock <td>.** 
20fa0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
20fb0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
20fc0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
20fd0 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
20fe0 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c  ix-nolock"..** <
20ff0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21000 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
21010 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
21020 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
21030 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
21040 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
21050 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
21060 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
21070 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
21080 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
21090 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
210a0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
210b0 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
210c0 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
210d0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
210e0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
210f0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
21100 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
21110 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
21120 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
21130 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
21140 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
21150 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
21160 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
21170 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
21180 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
21190 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
211a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
211b0 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
211c0 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
211d0 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
211e0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
211f0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
21200 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
21210 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
21220 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
21230 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
21240 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
21250 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
21260 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
21270 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
21280 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
21290 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
212a0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
212b0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
212c0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
212d0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
212e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
212f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
21300 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21310 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
21320 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
21330 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
21340 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
21350 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
21360 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
21370 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
21380 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
21390 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
213a0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
213b0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
213c0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
213d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
213e0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
213f0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
21400 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
21410 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
21420 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
21430 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
21440 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
21450 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21460 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
21470 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
21480 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
21490 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
214a0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
214b0 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
214c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
214d0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
214e0 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
214f0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
21500 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
21510 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
21520 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
21530 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
21540 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
21550 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
21560 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
21570 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
21580 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
21590 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
215a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
215b0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
215c0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
215d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
215e0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
215f0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
21600 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
21610 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
21620 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
21630 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
21640 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
21650 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
21660 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
21670 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
21680 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
21690 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
216a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
216b0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
216c0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
216d0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
216e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
216f0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
21700 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
21710 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
21720 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
21730 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
21740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
21750 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
21760 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
21770 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
21780 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
21790 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
217a0 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
217b0 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
217c0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
217d0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
217e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
217f0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
21800 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
21810 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
21820 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
21830 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
21840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
21850 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
21860 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
21870 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
21880 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
21890 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
218a0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
218b0 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
218c0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
218d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
218e0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
218f0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
21900 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
21910 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
21920 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
21930 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
21940 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
21950 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
21960 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
21970 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
21980 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
21990 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
219a0 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
219b0 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
219c0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
219d0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
219e0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
219f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
21a00 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21a10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21a20 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
21a30 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
21a40 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
21a50 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
21a60 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
21a70 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
21a80 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
21a90 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
21aa0 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
21ab0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
21ac0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
21ad0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
21ae0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
21af0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
21b00 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
21b10 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
21b20 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
21b30 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
21b40 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
21b50 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
21b60 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
21b70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
21b80 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
21b90 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
21ba0 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
21bb0 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
21bc0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
21bd0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
21be0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
21bf0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
21c00 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
21c10 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
21c20 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
21c30 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
21c40 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
21c50 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
21c60 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
21c70 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
21c80 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
21c90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
21ca0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
21cb0 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
21cc0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
21cd0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
21ce0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
21cf0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
21d00 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
21d10 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
21d20 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
21d30 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
21d40 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
21d50 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
21d60 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
21d70 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
21d80 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
21d90 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
21da0 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
21db0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
21dc0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
21dd0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
21de0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
21df0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
21e00 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21e10 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
21e20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
21e30 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
21e40 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
21e50 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
21e60 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
21e70 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
21e80 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
21e90 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
21ea0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
21eb0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
21ec0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
21ed0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
21ee0 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
21ef0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
21f00 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
21f10 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
21f20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
21f30 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
21f40 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
21f50 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
21f60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
21f70 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
21f80 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
21f90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
21fa0 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
21fb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
21fc0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
21fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
21fe0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
21ff0 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
22000 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
22010 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
22020 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
22030 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
22040 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
22050 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
22060 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
22070 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
22080 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
22090 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
220a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
220b0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
220c0 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
220d0 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
220e0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
220f0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
22100 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
22110 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
22120 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
22130 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
22140 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
22150 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
22160 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
22170 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
22180 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
22190 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
221a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
221b0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
221c0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
221d0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
221e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
221f0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
22200 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
22210 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
22220 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
22230 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
22240 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
22250 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
22260 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
22270 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
22280 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
22290 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
222a0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
222b0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
222c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
222d0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
222e0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
222f0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
22300 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
22310 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
22320 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
22330 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
22340 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
22350 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
22360 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
22370 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
22380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
22390 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
223a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
223b0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
223c0 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
223d0 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
223e0 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
223f0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
22400 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
22410 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
22420 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
22430 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
22440 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
22450 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
22460 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
22470 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
22480 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
22490 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
224a0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
224b0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
224c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
224d0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
224e0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
224f0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
22500 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
22510 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
22520 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
22530 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
22540 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
22550 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
22560 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
22570 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
22580 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
22590 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
225a0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
225b0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
225c0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
225d0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
225e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
225f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
22600 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
22610 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
22620 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
22630 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
22640 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
22650 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
22660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
22670 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
22680 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
22690 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
226a0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
226b0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
226c0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
226d0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
226e0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
226f0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
22700 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
22710 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
22720 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
22730 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
22740 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
22750 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
22760 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
22770 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
22780 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
22790 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
227a0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
227b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
227c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
227d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
227e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
227f0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
22800 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
22810 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
22820 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
22830 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
22840 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
22850 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
22860 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
22870 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
22880 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22890 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
228a0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
228b0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
228c0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
228d0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
228e0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
228f0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
22900 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
22910 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
22920 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
22930 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
22940 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
22950 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
22960 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
22970 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
22980 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
22990 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
229a0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
229b0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
229c0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
229d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
229e0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
229f0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
22a00 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
22a10 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
22a20 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
22a30 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
22a40 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
22a50 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
22a60 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
22a70 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
22a80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
22a90 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
22aa0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
22ab0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
22ac0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
22ad0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
22ae0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
22af0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
22b00 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
22b10 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
22b20 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
22b30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
22b40 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
22b50 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
22b60 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
22b70 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
22b80 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
22b90 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22ba0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
22bb0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
22bc0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
22bd0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
22be0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
22bf0 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
22c00 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
22c10 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
22c20 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
22c30 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
22c40 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
22c50 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
22c60 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
22c70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
22c80 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
22c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22ca0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
22cb0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
22cc0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
22cd0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
22ce0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
22cf0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
22d00 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
22d10 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
22d20 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
22d30 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
22d40 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
22d50 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
22d60 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
22d70 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
22d80 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
22d90 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
22da0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
22db0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
22dc0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
22dd0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
22de0 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
22df0 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
22e00 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
22e10 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
22e20 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
22e30 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
22e40 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
22e50 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
22e60 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
22e70 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
22e80 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
22e90 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
22ea0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
22eb0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
22ec0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
22ed0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
22ee0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
22ef0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
22f00 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
22f10 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
22f20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
22f30 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
22f40 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
22f50 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
22f60 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
22f70 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
22f80 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
22f90 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
22fa0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
22fb0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
22fc0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
22fd0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
22fe0 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
22ff0 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
23000 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
23010 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
23020 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
23030 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
23040 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
23050 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
23060 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
23070 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
23080 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
23090 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
230a0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
230b0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
230c0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
230d0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
230e0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
230f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
23100 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
23110 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
23120 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
23130 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
23140 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
23150 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
23160 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
23170 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
23180 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
23190 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
231a0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
231b0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
231c0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
231d0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
231e0 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
231f0 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
23200 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
23210 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
23220 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
23230 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
23240 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
23250 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
23260 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
23270 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
23280 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
23290 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
232a0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
232b0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
232c0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
232d0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
232e0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
232f0 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
23300 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
23310 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
23320 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
23330 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
23340 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
23350 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
23360 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
23370 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
23380 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
23390 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
233a0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
233b0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
233c0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
233d0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
233e0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
233f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
23400 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
23410 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
23420 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
23430 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
23440 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
23450 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
23460 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
23470 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
23480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
23490 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
234a0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
234b0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
234c0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
234d0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
234e0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
234f0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
23500 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
23510 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
23520 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
23530 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23540 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
23550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
23560 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23570 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
23580 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
23590 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
235a0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
235b0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
235c0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
235d0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
235e0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
235f0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
23600 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
23610 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
23620 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
23630 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
23640 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
23650 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
23660 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
23670 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
23680 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23690 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
236a0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
236b0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
236c0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
236d0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
236e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
236f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
23700 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
23710 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
23720 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
23730 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23740 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
23750 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
23760 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
23770 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
23780 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
23790 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
237a0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
237b0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
237c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
237d0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
237e0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
237f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
23800 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
23810 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23820 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
23830 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
23840 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
23850 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
23870 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
23880 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
23890 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
238a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
238b0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
238c0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
238d0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
238e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
238f0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
23900 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
23910 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
23920 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
23930 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
23940 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
23950 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
23960 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
23970 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23980 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
23990 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
239a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
239b0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
239c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
239d0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
239e0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
239f0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
23a00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23a10 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
23a20 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
23a30 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
23a40 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23a50 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
23a60 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
23a70 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
23a80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23a90 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
23aa0 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
23ab0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23ac0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
23ad0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
23ae0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
23af0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
23b00 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
23b10 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
23b20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
23b30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23b40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
23b50 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
23b60 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
23b70 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
23b80 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
23b90 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
23ba0 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
23bb0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
23bc0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
23bd0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
23be0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
23bf0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
23c00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
23c10 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
23c20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23c30 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
23c40 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
23c50 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
23c60 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
23c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
23c80 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
23c90 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
23ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
23cb0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
23cc0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
23cd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
23ce0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
23cf0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
23d00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
23d10 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
23d20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
23d30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23d40 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
23d50 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
23d60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23d70 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
23d80 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
23d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23da0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
23db0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
23dc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23dd0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
23de0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
23df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23e00 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
23e10 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
23e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23e30 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
23e40 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
23e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23e60 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
23e70 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
23e80 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
23e90 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
23ea0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
23eb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
23ec0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
23ed0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
23ee0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
23ef0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
23f00 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
23f10 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
23f20 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
23f30 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
23f40 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
23f50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
23f60 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
23f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23f80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
23f90 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
23fa0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
23fb0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
23fc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23fd0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
23fe0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
23ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24000 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
24010 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
24020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
24030 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
24040 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
24050 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
24060 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
24070 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
24080 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
24090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
240a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
240b0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
240c0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
240d0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
240e0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
240f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24100 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
24110 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
24120 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
24130 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
24140 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
24150 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
24160 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
24170 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
24180 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
24190 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
241a0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
241b0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
241c0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
241d0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
241e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
241f0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
24200 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
24210 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
24220 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
24230 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
24240 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
24250 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
24260 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
24270 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
24280 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
24290 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
242a0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
242b0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
242c0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
242d0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
242e0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
242f0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
24300 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
24310 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
24320 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
24330 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
24340 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
24350 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
24360 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
24370 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
24380 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
24390 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
243a0 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
243b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
243c0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
243d0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
243e0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
243f0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
24400 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
24410 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
24420 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
24430 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
24440 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
24450 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
24460 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
24470 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
24480 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
24490 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
244a0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
244b0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
244c0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
244d0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
244e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
244f0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
24500 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
24510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24520 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
24530 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
24540 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
24550 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
24560 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
24570 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
24580 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
24590 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
245a0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
245b0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
245c0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
245d0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
245e0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
245f0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
24600 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
24610 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
24620 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
24630 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
24640 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
24650 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
24660 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
24670 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
24680 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
24690 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
246a0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
246b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
246c0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
246d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
246e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
246f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
24700 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
24710 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24720 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
24730 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
24740 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
24750 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
24760 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
24770 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
24780 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
24790 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
247a0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
247b0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
247c0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
247d0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
247e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
247f0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
24800 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
24810 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
24820 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
24830 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
24840 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
24850 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
24860 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
24870 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
24880 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
24890 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
248a0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
248b0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
248c0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
248d0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
248e0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
248f0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
24900 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
24910 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
24920 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
24930 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
24940 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
24950 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
24960 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
24970 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
24980 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
24990 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
249a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
249b0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
249c0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
249d0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
249e0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
249f0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
24a00 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
24a10 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
24a20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24a30 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
24a40 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
24a50 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
24a60 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
24a70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
24a80 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
24a90 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
24aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
24ab0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
24ac0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
24ad0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
24ae0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
24af0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
24b00 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
24b10 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
24b20 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
24b30 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
24b40 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
24b50 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
24b60 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
24b70 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
24b80 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
24b90 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
24ba0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
24bb0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
24bc0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
24bd0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
24be0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
24bf0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
24c00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
24c10 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
24c20 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
24c30 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
24c40 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
24c50 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
24c60 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
24c70 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
24c80 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
24c90 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
24ca0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
24cb0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
24cc0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
24cd0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
24ce0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
24cf0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
24d00 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
24d10 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
24d20 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
24d30 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
24d40 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
24d50 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
24d60 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
24d70 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
24d80 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
24d90 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
24da0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
24db0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
24dc0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
24dd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
24de0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
24df0 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
24e00 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
24e10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24e20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
24e30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
24e40 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
24e50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
24e60 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
24e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
24e80 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
24e90 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
24ea0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
24eb0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
24ec0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
24ed0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
24ee0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
24ef0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
24f00 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
24f10 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
24f20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
24f30 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
24f40 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
24f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
24f60 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
24f70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
24f80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
24f90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24fa0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
24fb0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
24fc0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
24fd0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
24fe0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24ff0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25000 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25010 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25020 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25030 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25040 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25050 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
25060 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25070 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25080 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25090 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
250a0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
250b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
250c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
250d0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
250e0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
250f0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
25100 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
25110 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
25120 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
25130 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
25140 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
25150 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
25160 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
25170 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
25180 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
25190 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
251a0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
251b0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
251c0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
251d0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
251e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
251f0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
25200 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
25210 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
25220 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
25230 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
25240 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
25250 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
25260 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25280 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25290 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
252a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
252b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
252c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
252d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
252e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
252f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25300 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25310 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25320 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
25330 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
25340 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
25350 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
25360 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
25370 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
25380 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
25390 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
253a0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
253b0 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
253c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
253d0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
253e0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
253f0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
25400 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25410 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
25420 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
25430 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
25440 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
25450 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25470 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
25480 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
25490 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
254a0 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
254b0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
254c0 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
254d0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
254e0 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
254f0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
25500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25510 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
25520 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
25530 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
25540 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
25550 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
25560 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
25570 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
25580 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
25590 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
255a0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
255b0 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
255c0 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
255d0 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
255e0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
255f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
25600 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
25610 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
25620 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
25630 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
25640 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
25650 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
25660 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
25670 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
25680 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
25690 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
256a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
256b0 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
256c0 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
256d0 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
256e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
256f0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
25700 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
25710 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
25720 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
25730 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
25740 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
25750 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
25760 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
25770 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
25780 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
25790 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
257a0 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
257b0 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
257c0 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
257d0 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
257e0 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
257f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
25800 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
25810 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
25820 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
25830 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
25840 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
25850 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
25860 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
25870 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
25880 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
25890 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
258a0 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
258b0 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
258c0 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
258d0 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
258e0 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
258f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
25900 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
25910 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
25920 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
25930 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
25940 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
25950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25960 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
25970 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
25980 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
25990 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
259a0 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
259b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
259c0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
259d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
259e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
259f0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
25a00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25a10 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
25a20 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
25a30 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
25a40 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
25a50 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
25a60 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
25a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25a80 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
25a90 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
25aa0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
25ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25ac0 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
25ad0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
25ae0 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
25af0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
25b00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
25b10 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
25b20 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
25b30 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
25b40 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
25b50 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
25b60 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
25b70 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
25b80 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
25b90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
25ba0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
25bb0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
25bc0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
25bd0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
25be0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
25bf0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
25c00 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
25c10 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
25c20 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
25c30 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
25c40 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
25c50 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
25c60 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
25c70 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
25c80 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
25c90 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
25ca0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
25cb0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
25cc0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
25cd0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
25ce0 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
25cf0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
25d00 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
25d10 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
25d20 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
25d30 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
25d40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
25d50 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
25d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25d70 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
25d80 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
25d90 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
25da0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25db0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
25dc0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25dd0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
25de0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
25df0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
25e00 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
25e10 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
25e20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
25e30 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
25e40 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
25e50 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
25e60 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
25e70 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
25e80 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
25e90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25ea0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
25eb0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
25ec0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
25ed0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
25ee0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
25ef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25f00 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
25f10 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
25f20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
25f30 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
25f40 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
25f50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25f60 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
25f70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
25f80 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
25f90 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
25fa0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
25fb0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
25fc0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
25fd0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
25fe0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
25ff0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
26000 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
26010 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
26020 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26030 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
26040 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
26050 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
26060 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
26070 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
26080 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
26090 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
260a0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
260b0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
260c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
260d0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
260e0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
260f0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
26100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26110 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
26120 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
26130 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
26140 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
26150 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
26160 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
26170 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
26180 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
26190 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
261a0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
261b0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
261c0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
261d0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
261e0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
261f0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
26200 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
26210 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
26220 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
26230 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
26240 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
26250 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
26260 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
26270 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
26280 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
26290 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
262a0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
262b0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
262c0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
262d0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
262e0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
262f0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
26300 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
26310 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
26320 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
26330 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
26340 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
26350 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26360 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
26370 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
26380 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
26390 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
263a0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
263b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
263c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
263d0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
263e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
263f0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
26400 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
26410 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
26420 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
26430 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
26440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26450 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
26460 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
26470 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
26480 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
26490 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
264a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
264b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
264c0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
264d0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
264e0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
264f0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
26500 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
26510 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
26520 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
26530 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
26540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
26550 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
26560 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
26570 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
26580 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
26590 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
265a0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
265b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
265c0 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
265d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
265e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
265f0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
26600 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26610 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
26620 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
26630 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
26640 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26650 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
26660 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26670 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
26680 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
26690 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
266a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
266b0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
266c0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
266d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
266e0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
266f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
26700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
26710 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
26720 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
26730 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
26740 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
26750 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
26760 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
26770 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26780 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
267a0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
267b0 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
267c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
267d0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
267e0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
267f0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
26800 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
26810 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
26820 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
26830 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
26840 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
26850 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
26860 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
26870 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
26880 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26890 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
268a0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
268b0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
268c0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
268d0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
268e0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
268f0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
26900 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
26910 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
26920 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
26930 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
26940 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
26950 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
26960 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
26970 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
26980 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
26990 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
269a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
269b0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
269c0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
269d0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
269e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
269f0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
26a00 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
26a10 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
26a20 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
26a30 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
26a40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26a50 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
26a60 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
26a70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
26a80 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
26a90 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
26aa0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
26ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
26ac0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
26ad0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
26ae0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
26af0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
26b00 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
26b10 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
26b20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
26b30 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
26b40 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
26b50 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
26b60 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
26b70 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
26b80 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
26b90 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
26ba0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
26bb0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
26bc0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
26bd0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
26be0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
26bf0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
26c00 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
26c10 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
26c20 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
26c30 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
26c40 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
26c50 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
26c60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26c70 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
26c80 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
26c90 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
26ca0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
26cb0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
26cc0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
26cd0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
26ce0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
26cf0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
26d00 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
26d10 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
26d20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
26d30 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
26d40 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
26d50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
26d60 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
26d70 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
26d80 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  meter..**.** ^(I
26d90 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
26da0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
26db0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
26dc0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
26dd0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
26de0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
26df0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
26e00 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
26e10 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
26e20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
26e30 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
26e40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
26e50 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
26e60 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
26e70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26e80 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
26e90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26ea0 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
26eb0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
26ec0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
26ed0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
26ee0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
26ef0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
26f00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
26f10 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
26f20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26f30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
26f40 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
26f50 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
26f60 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
26f70 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
26f80 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
26f90 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
26fa0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
26fb0 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
26fc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26fd0 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
26fe0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
26ff0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
27000 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
27010 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
27020 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
27030 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
27040 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
27050 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
27060 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
27070 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
27080 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
27090 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
270a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
270b0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
270c0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
270d0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
270e0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
270f0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
27100 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
27110 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
27120 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
27130 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
27140 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
27150 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
27160 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
27170 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
27180 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
27190 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
271a0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
271b0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
271c0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
271d0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
271e0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
271f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
27200 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
27210 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
27220 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
27230 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
27240 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
27250 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
27260 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
27270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27280 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
27290 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
272a0 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
272b0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
272c0 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
272d0 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
272e0 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
272f0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
27300 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
27310 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
27320 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
27330 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
27340 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
27350 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
27360 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
27370 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
27380 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
27390 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
273a0 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
273b0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
273c0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
273d0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
273e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
273f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
27400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27410 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
27420 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
27430 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
27440 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
27450 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
27460 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
27470 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
27480 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
27490 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
274a0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
274b0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
274c0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
274d0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
274e0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
274f0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
27500 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
27510 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
27520 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
27530 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
27540 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
27550 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
27560 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
27570 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
27580 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
27590 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
275a0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
275b0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
275c0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
275d0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
275e0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
275f0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
27600 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
27610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27620 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
27630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
27640 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
27650 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
27660 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
27670 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
27680 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27690 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
276a0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
276b0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
276c0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
276d0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
276e0 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
276f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27700 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
27710 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
27720 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
27730 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
27740 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
27750 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
27760 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
27770 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
27780 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
27790 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
277a0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
277b0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
277c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
277d0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
277e0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
277f0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
27800 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
27810 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
27820 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
27830 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
27840 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
27850 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
27860 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
27870 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
27880 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
27890 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
278a0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
278b0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
278c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
278d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
278e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
278f0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
27900 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
27910 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27920 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
27930 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
27940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27950 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
27960 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
27970 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
27980 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
27990 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
279a0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
279b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
279c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
279d0 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
279e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
279f0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
27a00 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
27a10 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
27a20 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
27a30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
27a40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27a50 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
27a60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
27a70 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
27a80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27a90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27aa0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
27ab0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
27ac0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
27ad0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
27ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
27af0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
27b00 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
27b10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
27b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27b30 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
27b40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27b50 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
27b60 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27b70 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
27b80 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
27b90 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
27ba0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
27bb0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
27bc0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
27bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27be0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
27bf0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
27c00 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
27c10 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
27c20 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
27c30 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
27c40 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
27c50 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
27c60 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
27c70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
27c80 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
27c90 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
27ca0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
27cb0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
27cc0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
27cd0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
27ce0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
27cf0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
27d00 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
27d10 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
27d20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
27d30 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
27d40 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
27d50 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
27d60 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
27d70 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
27d80 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
27d90 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
27da0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
27db0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27dc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
27dd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
27de0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27df0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
27e00 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
27e10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27e20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
27e30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
27e40 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
27e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
27e60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27e70 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
27e80 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
27e90 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
27ea0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
27eb0 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
27ec0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
27ed0 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
27ee0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
27ef0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
27f00 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
27f10 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
27f20 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
27f30 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
27f40 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
27f50 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
27f60 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
27f70 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
27f80 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
27f90 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
27fa0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
27fb0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
27fc0 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
27fd0 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
27fe0 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
27ff0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
28000 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
28010 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
28020 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
28030 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
28040 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
28050 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
28060 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
28070 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
28080 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
28090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
280a0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
280b0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
280c0 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
280d0 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
280e0 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
280f0 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
28100 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
28110 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
28120 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
28130 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
28140 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
28150 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
28160 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
28170 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
28180 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
28190 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
281a0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
281b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
281c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
281d0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
281e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
281f0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
28200 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
28210 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
28220 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28230 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
28240 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28250 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
28260 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
28270 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
28280 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
28290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
282a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
282b0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
282c0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
282d0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
282e0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
282f0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
28300 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
28310 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
28320 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
28330 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
28340 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
28350 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
28360 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
28370 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
28380 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
28390 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
283a0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
283b0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
283c0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
283d0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
283e0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
283f0 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
28400 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
28410 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
28420 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
28430 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
28440 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28450 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
28460 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
28470 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
28480 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
28490 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
284a0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
284b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
284c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
284d0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
284e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
284f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
28500 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
28510 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
28520 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28530 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
28540 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
28550 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
28560 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
28570 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
28580 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
28590 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
285a0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
285b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
285c0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
285d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
285e0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
285f0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
28600 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
28610 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
28620 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28630 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
28640 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28660 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
28670 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
28680 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
28690 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
286a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
286b0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
286c0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
286d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
286e0 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
286f0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
28700 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
28710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
28720 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
28730 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
28740 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
28750 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
28760 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
28770 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
28780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
28790 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
287a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
287b0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
287c0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
287d0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
287e0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
287f0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
28800 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
28810 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
28820 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
28830 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
28840 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
28850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
28860 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
28870 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
28880 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
28890 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
288a0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
288b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
288c0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
288d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
288e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
288f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
28900 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
28910 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
28920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28930 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
28940 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
28950 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
28960 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28970 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
28980 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
28990 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
289a0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
289b0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
289c0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
289d0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
289e0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
289f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
28a00 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
28a10 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
28a20 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
28a30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
28a40 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
28a50 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
28a60 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
28a70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
28a80 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
28a90 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
28aa0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
28ab0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
28ac0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
28ad0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
28ae0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
28af0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
28b00 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
28b10 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
28b20 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
28b30 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
28b40 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
28b50 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
28b60 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
28b70 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
28b80 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
28b90 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
28ba0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
28bb0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
28bc0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
28bd0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
28be0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
28bf0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
28c00 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
28c10 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
28c20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
28c30 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
28c40 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
28c50 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
28c60 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
28c70 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
28c80 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
28c90 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
28ca0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28cb0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
28cc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
28cd0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
28ce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
28cf0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
28d00 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
28d10 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
28d20 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
28d30 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
28d40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
28d50 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
28d60 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
28d70 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
28d80 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
28d90 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
28da0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
28db0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
28dc0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
28dd0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28de0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
28df0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
28e00 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
28e10 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
28e20 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
28e30 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
28e40 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
28e50 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
28e60 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
28e70 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
28e80 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
28e90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
28ea0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
28eb0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
28ec0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
28ed0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
28ee0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
28ef0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
28f00 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
28f10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28f20 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
28f30 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
28f40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
28f50 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
28f60 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
28f70 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
28f80 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
28f90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28fa0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
28fb0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
28fc0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
28fd0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
28fe0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
28ff0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
29000 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
29010 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
29020 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
29030 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
29040 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
29050 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
29060 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
29070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29080 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
29090 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
290a0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
290b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
290c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
290d0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
290e0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
290f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
29100 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
29110 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
29120 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
29130 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
29140 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
29150 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
29160 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
29170 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
29180 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
29190 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
291a0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
291b0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
291c0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
291d0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
291e0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
291f0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
29200 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
29210 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
29220 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
29230 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
29240 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
29250 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
29260 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
29270 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
29280 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
29290 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
292a0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
292b0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
292c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
292d0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
292e0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
292f0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
29300 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
29310 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
29320 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
29330 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
29340 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
29350 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
29360 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
29370 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
29380 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
29390 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
293a0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
293b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
293c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
293d0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
293e0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
293f0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
29400 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
29410 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
29420 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
29430 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
29440 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
29450 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
29460 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
29470 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
29480 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
29490 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
294a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
294b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
294c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
294d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
294e0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
294f0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
29500 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
29510 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
29520 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
29530 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
29540 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
29550 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
29560 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
29570 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29580 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29590 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
295a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
295b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
295c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
295d0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
295e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
295f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
29600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
29610 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
29620 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
29630 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29640 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
29650 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
29660 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
29670 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29680 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
29690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
296a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
296b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
296c0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
296d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
296e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
296f0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
29700 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
29710 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
29720 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29730 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
29740 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
29750 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
29760 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
29770 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
29780 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
29790 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
297a0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
297b0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
297c0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
297d0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
297e0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
297f0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
29800 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
29810 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
29820 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
29830 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
29840 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29850 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
29860 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
29870 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
29880 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
29890 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
298a0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
298b0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
298c0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
298d0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
298e0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
298f0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
29900 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
29910 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
29920 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
29930 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
29940 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
29950 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
29960 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
29970 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
29980 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
29990 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
299a0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
299b0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
299c0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
299d0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
299e0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
299f0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
29a00 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
29a10 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
29a20 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
29a30 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
29a40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
29a50 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
29a60 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
29a70 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
29a80 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
29a90 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
29aa0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
29ab0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
29ac0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
29ad0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
29ae0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
29af0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
29b00 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
29b10 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
29b20 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
29b30 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
29b40 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
29b50 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
29b60 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
29b70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29b80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
29b90 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
29ba0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
29bb0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29bc0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
29bd0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29be0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29bf0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
29c00 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
29c10 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
29c20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
29c30 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
29c40 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
29c50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29c60 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
29c70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29c80 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
29c90 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
29ca0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
29cb0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
29cc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29cd0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
29ce0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
29cf0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
29d00 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
29d10 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
29d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
29d30 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
29d40 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
29d50 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
29d60 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
29d70 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
29d80 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
29d90 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
29da0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
29db0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
29dc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
29dd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29de0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
29df0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
29e00 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
29e10 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
29e20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
29e30 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
29e40 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
29e50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
29e60 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
29e70 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
29e80 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
29e90 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
29ea0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
29eb0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
29ec0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
29ed0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
29ee0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
29ef0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
29f00 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
29f10 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
29f20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
29f30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
29f40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
29f50 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
29f60 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
29f70 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
29f80 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
29f90 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
29fa0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
29fb0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
29fc0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
29fd0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
29fe0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
29ff0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2a000 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2a010 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2a020 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2a030 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2a040 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2a050 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2a060 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2a070 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2a080 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2a090 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2a0a0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2a0b0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2a0c0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2a0d0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2a0e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2a0f0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2a100 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2a110 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2a120 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2a130 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2a140 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2a150 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2a160 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2a170 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2a180 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2a190 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2a1a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2a1b0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2a1c0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2a1d0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2a1e0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2a1f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2a200 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2a210 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2a220 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2a230 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2a240 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2a250 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a260 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2a270 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2a280 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2a290 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2a2a0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2a2b0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2a2c0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2a2d0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2a2e0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2a2f0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2a300 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2a310 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2a320 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2a330 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2a340 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2a350 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2a360 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2a370 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2a380 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2a390 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2a3a0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2a3b0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2a3c0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2a3d0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2a3e0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2a3f0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2a400 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2a410 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2a420 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2a430 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2a440 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2a450 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2a460 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2a470 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2a480 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2a490 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2a4a0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2a4b0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2a4c0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2a4d0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2a4e0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2a4f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2a500 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2a510 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2a520 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2a530 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2a540 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2a550 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2a560 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2a570 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2a580 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2a590 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2a5a0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2a5b0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2a5c0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2a5d0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2a5e0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2a5f0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2a600 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2a610 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2a620 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2a630 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2a640 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2a650 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2a660 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2a670 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2a680 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2a690 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2a6a0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2a6b0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2a6c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2a6d0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2a6e0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2a6f0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2a700 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2a710 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2a720 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2a730 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2a740 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2a750 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2a760 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2a770 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2a780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2a790 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2a7a0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2a7b0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2a7c0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2a7d0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2a7e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2a7f0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2a800 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2a810 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2a820 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2a830 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2a840 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2a850 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2a860 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2a870 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2a880 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2a890 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2a8a0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2a8b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2a8c0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2a8d0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2a8e0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2a8f0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2a900 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2a910 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2a920 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2a930 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2a940 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2a950 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2a960 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2a970 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2a980 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2a990 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2a9a0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2a9b0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2a9c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2a9d0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2a9e0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2a9f0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2aa00 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2aa10 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2aa20 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2aa30 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2aa40 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2aa50 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2aa60 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2aa70 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2aa80 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2aa90 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2aaa0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2aab0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2aac0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2aad0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2aae0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2aaf0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2ab00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ab10 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2ab20 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2ab30 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2ab40 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2ab50 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2ab60 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2ab70 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2ab80 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2ab90 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2aba0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2abb0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2abc0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2abd0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2abe0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2abf0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2ac00 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2ac10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2ac20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ac30 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2ac40 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2ac50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ac60 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2ac70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2ac80 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2ac90 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2aca0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2acb0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2acc0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2acd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2ace0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2acf0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2ad00 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2ad10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
2ad20 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2ad30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ad40 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2ad50 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2ad60 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2ad70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ad80 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2ad90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ada0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2adb0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2adc0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2add0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2ade0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2adf0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2ae00 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2ae10 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2ae20 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2ae30 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2ae40 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ae50 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2ae60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2ae70 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2ae80 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2ae90 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2aea0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2aeb0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2aec0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2aed0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2aee0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2aef0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2af00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2af10 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2af20 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2af30 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2af40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2af50 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2af60 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2af70 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2af80 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2af90 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2afa0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2afb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2afc0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2afd0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2afe0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2aff0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2b000 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2b010 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2b020 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2b030 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2b040 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2b050 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2b060 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2b070 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2b080 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2b0a0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2b0b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b0c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2b0d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2b0e0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2b0f0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2b100 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2b110 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2b120 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2b130 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2b140 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2b150 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2b160 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2b170 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2b180 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2b190 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2b1a0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2b1b0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2b1c0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2b1d0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2b1e0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2b1f0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2b200 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2b210 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2b220 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2b230 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2b240 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2b250 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2b260 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2b270 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2b280 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2b290 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2b2a0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2b2b0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2b2c0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2b2d0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2b2e0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2b2f0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2b300 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2b310 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2b320 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2b330 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2b340 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2b350 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2b360 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2b370 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2b380 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2b390 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2b3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2b3b0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2b3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2b3d0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2b3e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2b3f0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2b400 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2b410 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2b420 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2b430 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2b440 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2b450 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
2b460 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
2b470 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b480 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2b490 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2b4a0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2b4b0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2b4c0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2b4d0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2b4e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2b4f0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2b500 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2b510 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2b520 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2b530 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2b540 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2b550 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2b560 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2b570 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2b580 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2b590 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2b5a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2b5b0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2b5c0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2b5d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2b5e0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2b5f0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2b600 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2b610 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2b620 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2b630 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2b640 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2b650 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2b660 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2b670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2b680 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2b690 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2b6a0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2b6b0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2b6c0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2b6d0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2b6e0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2b6f0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2b700 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2b710 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2b720 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2b730 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2b740 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b750 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2b760 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2b770 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2b780 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2b790 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b7a0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2b7b0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2b7c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2b7d0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2b7e0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2b7f0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2b800 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2b810 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2b820 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b830 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2b840 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2b850 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2b860 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2b870 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2b880 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2b890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2b8a0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2b8b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2b8c0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2b8d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2b8e0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2b8f0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2b900 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2b910 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2b920 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2b930 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2b940 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2b950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2b960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2b970 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2b980 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2b990 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2b9a0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2b9b0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2b9c0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2b9d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2b9e0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2b9f0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2ba00 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2ba10 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2ba20 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2ba30 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2ba40 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2ba50 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2ba60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ba70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ba80 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2ba90 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2baa0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2bab0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2bac0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2bad0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2bae0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2baf0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2bb00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2bb10 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2bb20 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2bb30 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2bb40 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2bb50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2bb60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bb70 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2bb80 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2bb90 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2bba0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2bbb0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2bbc0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2bbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bbe0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2bbf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2bc00 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2bc10 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2bc20 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2bc30 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2bc40 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2bc50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bc60 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2bc70 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2bc80 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2bc90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2bca0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2bcb0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2bcc0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2bcd0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2bce0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2bcf0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2bd00 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2bd10 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2bd20 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2bd30 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2bd40 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2bd50 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2bd60 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2bd70 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2bd80 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2bd90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2bda0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2bdb0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2bdc0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2bdd0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2bde0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2bdf0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2be00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2be10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2be20 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2be30 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2be40 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2be50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2be60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2be70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2be80 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2be90 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2bea0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2beb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2bec0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2bed0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2bee0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2bef0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bf00 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2bf10 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2bf20 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2bf30 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2bf40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2bf50 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2bf60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2bf70 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2bf80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2bf90 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2bfa0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2bfb0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2bfc0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2bfd0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2bfe0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2bff0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2c000 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2c010 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c020 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2c030 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2c040 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2c050 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2c060 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2c070 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2c080 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2c090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c0a0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2c0b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c0c0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2c0d0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2c0e0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2c0f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2c100 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2c110 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2c120 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2c130 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2c140 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2c150 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2c160 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2c170 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2c180 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2c190 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2c1a0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2c1b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2c1c0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2c1d0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2c1e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2c1f0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2c200 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2c210 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2c220 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2c230 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c240 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2c250 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2c260 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c270 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2c280 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2c290 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2c2a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2c2b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2c2c0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2c2d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c2e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2c2f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2c300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2c310 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2c320 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2c330 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2c340 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2c350 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2c360 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2c370 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2c380 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2c390 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2c3a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2c3b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2c3c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2c3d0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2c3e0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2c3f0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2c400 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2c410 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2c420 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2c430 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2c440 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2c450 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2c460 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2c470 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2c480 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2c490 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2c4a0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2c4b0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2c4c0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2c4d0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2c4e0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2c4f0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2c500 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2c510 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2c520 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2c530 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2c540 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2c550 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2c560 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2c570 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2c580 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2c590 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2c5a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2c5b0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2c5c0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2c5d0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2c5e0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2c5f0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2c600 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
2c610 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2c620 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2c630 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2c640 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
2c650 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2c660 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2c670 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2c680 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2c690 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2c6a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2c6b0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2c6c0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2c6d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2c6e0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2c6f0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2c700 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2c710 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2c720 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2c730 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2c740 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2c750 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
2c760 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
2c770 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2c780 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2c790 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2c7a0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2c7b0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2c7c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2c7d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2c7e0 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
2c7f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2c800 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
2c810 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
2c820 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
2c830 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
2c840 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
2c850 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2c860 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2c870 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2c880 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
2c890 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2c8a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2c8b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2c8c0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2c8d0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
2c8e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2c8f0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2c900 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2c910 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
2c920 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2c930 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2c940 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
2c950 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
2c960 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
2c970 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2c980 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
2c990 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2c9a0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2c9b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2c9c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2c9d0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2c9e0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2c9f0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2ca00 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2ca10 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2ca20 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2ca30 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2ca40 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2ca50 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2ca60 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2ca70 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2ca80 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2ca90 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2caa0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2cab0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2cac0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2cad0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2cae0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2caf0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2cb00 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2cb10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2cb20 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2cb30 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2cb40 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2cb50 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2cb60 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2cb70 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2cb80 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2cb90 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2cba0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2cbb0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2cbc0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2cbd0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2cbe0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2cbf0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2cc00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2cc10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2cc20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2cc30 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2cc40 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2cc50 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2cc60 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2cc70 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2cc80 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2cc90 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2cca0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2ccb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2ccc0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2ccd0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2cce0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2ccf0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2cd00 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2cd10 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2cd20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2cd30 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2cd40 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2cd50 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2cd60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cd70 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2cd80 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2cd90 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2cda0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2cdb0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2cdc0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2cdd0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2cde0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2cdf0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2ce00 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2ce10 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2ce20 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2ce30 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2ce40 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2ce50 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2ce60 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2ce70 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2ce80 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2ce90 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2cea0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2ceb0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2cec0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2ced0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2cee0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2cef0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2cf00 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2cf10 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2cf20 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2cf30 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2cf40 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2cf50 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2cf60 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2cf70 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2cf80 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2cf90 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2cfa0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2cfb0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2cfc0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2cfd0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2cfe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2cff0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2d000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d010 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2d020 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2d030 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2d040 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2d050 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2d060 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2d070 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d080 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2d090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d0a0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2d0b0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2d0c0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2d0d0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2d0e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d0f0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2d100 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2d110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d120 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2d130 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2d140 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2d150 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2d160 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2d170 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2d180 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2d190 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2d1a0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2d1b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2d1c0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2d1d0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2d1e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2d1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d200 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2d210 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2d220 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2d230 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2d240 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2d250 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d260 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2d270 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2d280 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2d290 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2d2a0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2d2b0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2d2c0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2d2d0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2d2e0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2d2f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d300 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2d310 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2d320 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d330 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
2d340 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
2d350 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
2d360 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
2d370 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
2d380 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
2d390 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
2d3a0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2d3b0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
2d3c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2d3d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d3e0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2d3f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2d400 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2d410 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2d420 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2d430 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2d440 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2d450 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2d460 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2d470 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2d480 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2d490 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2d4a0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2d4b0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2d4c0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2d4d0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2d4e0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2d4f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2d500 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2d510 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2d520 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2d530 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2d540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d550 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2d560 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2d570 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d580 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2d590 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2d5b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2d5c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d5d0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2d5e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2d5f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2d600 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2d610 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d620 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2d630 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2d640 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2d650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2d660 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d670 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2d680 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2d690 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d6a0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2d6b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2d6c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2d6d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d6e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d6f0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2d700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2d710 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d720 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2d730 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2d740 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2d750 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d760 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
2d770 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
2d780 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
2d790 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2d7a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d7b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
2d7c0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2d7d0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
2d7e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d7f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
2d800 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2d810 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
2d820 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
2d830 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
2d840 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2d850 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2d860 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2d870 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d880 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2d890 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2d8a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2d8b0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2d8c0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2d8d0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2d8e0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2d8f0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2d900 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2d910 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2d920 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2d930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d940 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2d950 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2d960 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2d970 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2d980 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2d990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d9a0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2d9b0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2d9c0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2d9d0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2d9e0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2d9f0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2da00 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2da10 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2da20 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2da30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2da40 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2da50 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2da60 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2da70 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2da80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2da90 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2daa0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2dab0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2dac0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2dad0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2dae0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2daf0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2db00 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2db10 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2db20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2db30 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2db40 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2db50 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2db60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2db70 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2db80 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2db90 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2dba0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2dbb0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2dbc0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2dbd0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2dbe0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2dbf0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2dc00 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2dc10 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2dc20 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2dc30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2dc40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2dc50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2dc60 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2dc70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2dc80 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2dc90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2dca0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2dcb0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2dcc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dcd0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2dce0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2dcf0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2dd00 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2dd10 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2dd20 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2dd30 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2dd40 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2dd50 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2dd60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2dd70 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2dd80 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2dd90 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2dda0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2ddb0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2ddc0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2ddd0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2dde0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ddf0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2de00 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2de10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2de20 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2de30 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2de40 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2de50 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2de60 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2de70 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2de80 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2de90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2dea0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2deb0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2dec0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2ded0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2dee0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2def0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2df00 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2df10 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2df20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2df30 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2df40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2df50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2df60 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2df70 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2df80 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2df90 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2dfa0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2dfb0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2dfc0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2dfd0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2dfe0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2dff0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2e000 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2e010 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2e020 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2e030 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2e040 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2e050 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e060 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2e070 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2e080 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e090 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e0a0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2e0b0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2e0c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2e0d0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2e0e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2e0f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2e100 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e110 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2e120 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2e130 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e140 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2e150 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2e160 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2e170 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2e180 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2e190 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2e1a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2e1b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2e1c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2e1d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2e1e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2e1f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2e200 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2e210 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2e220 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2e230 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2e240 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2e250 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2e260 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
2e270 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
2e280 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
2e290 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
2e2a0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
2e2b0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
2e2c0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
2e2d0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
2e2e0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
2e2f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2e300 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
2e310 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2e320 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2e330 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2e340 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2e350 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2e360 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
2e370 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
2e380 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2e390 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2e3a0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
2e3b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e3c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2e3d0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
2e3e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
2e3f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
2e400 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
2e410 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2e420 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2e430 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2e440 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2e450 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2e460 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
2e470 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2e480 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2e490 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
2e4a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
2e4b0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2e4c0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2e4d0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
2e4e0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
2e4f0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
2e500 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
2e510 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
2e520 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
2e530 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
2e540 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2e550 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2e560 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2e570 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2e580 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
2e590 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2e5a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2e5b0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2e5c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2e5d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2e5e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2e5f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2e600 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
2e610 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
2e620 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2e630 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2e640 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2e650 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2e660 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
2e670 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
2e680 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
2e690 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2e6a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2e6b0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
2e6c0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
2e6d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
2e6e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2e6f0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
2e700 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
2e710 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2e720 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2e730 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2e740 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2e750 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2e760 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2e770 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2e780 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2e790 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2e7a0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
2e7b0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2e7c0 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
2e7d0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
2e7e0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2e7f0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2e800 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2e810 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2e820 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2e830 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2e840 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2e850 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
2e860 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
2e870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e880 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2e890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e8a0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2e8b0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2e8c0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2e8d0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2e8e0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2e8f0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
2e900 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2e910 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2e920 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2e930 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2e940 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2e950 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2e960 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2e970 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2e980 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2e990 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2e9a0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2e9b0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2e9c0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2e9d0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2e9e0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2e9f0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2ea00 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2ea10 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2ea20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
2ea30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
2ea40 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
2ea50 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
2ea60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
2ea70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
2ea80 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
2ea90 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
2eaa0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2eab0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
2eac0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
2ead0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
2eae0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2eaf0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2eb00 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2eb10 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2eb20 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2eb30 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2eb40 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2eb50 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
2eb60 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2eb70 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2eb80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2eb90 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2eba0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
2ebb0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
2ebc0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2ebd0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2ebe0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2ebf0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
2ec00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2ec10 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2ec20 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2ec30 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2ec40 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
2ec50 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
2ec60 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
2ec70 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2ec80 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2ec90 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2eca0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
2ecb0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2ecc0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
2ecd0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
2ece0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
2ecf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ed00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2ed10 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
2ed20 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
2ed30 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2ed40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ed50 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
2ed60 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
2ed70 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
2ed80 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2ed90 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
2eda0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
2edb0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
2edc0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2edd0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
2ede0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
2edf0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
2ee00 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
2ee10 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
2ee20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2ee30 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
2ee40 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
2ee50 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
2ee60 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
2ee70 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
2ee80 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
2ee90 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2eea0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
2eeb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2eec0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
2eed0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
2eee0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2eef0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2ef00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2ef10 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
2ef20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2ef30 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2ef40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2ef50 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2ef60 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2ef70 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2ef80 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2ef90 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2efa0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2efb0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2efc0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2efd0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
2efe0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2eff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
2f000 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
2f010 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
2f020 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
2f030 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
2f040 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
2f050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f060 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
2f070 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
2f080 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
2f090 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2f0a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2f0b0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
2f0c0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
2f0d0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2f0e0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2f0f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2f100 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2f110 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2f120 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2f130 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2f140 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2f150 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2f160 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
2f170 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2f180 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2f190 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
2f1a0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
2f1b0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
2f1c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2f1d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2f1e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2f1f0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
2f200 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
2f210 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
2f220 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
2f230 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
2f240 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
2f250 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f260 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
2f270 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f280 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2f290 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2f2a0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2f2b0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2f2c0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2f2d0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2f2e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2f2f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2f300 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2f310 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2f320 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2f330 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2f340 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f350 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2f360 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2f370 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2f380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2f390 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2f3a0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2f3b0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2f3c0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2f3d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2f3e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2f3f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2f400 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2f410 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2f420 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2f430 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2f440 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2f450 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2f460 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f470 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2f480 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2f490 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2f4a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2f4b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2f4c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2f4d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2f4e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f4f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2f500 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2f510 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2f520 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2f530 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2f540 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2f550 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2f560 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f570 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2f580 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2f590 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2f5a0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2f5b0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2f5c0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2f5d0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2f5e0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2f5f0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2f600 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2f610 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2f620 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f630 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f640 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f650 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2f660 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
2f670 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2f680 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2f690 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2f6a0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
2f6b0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2f6c0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2f6d0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2f6e0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2f6f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2f700 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2f710 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2f720 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2f730 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2f740 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2f750 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2f760 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2f770 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2f780 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2f790 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2f7a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2f7b0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2f7c0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2f7d0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2f7e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f7f0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2f800 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2f810 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2f820 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f830 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2f840 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2f850 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2f860 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2f870 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2f880 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2f890 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2f8a0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2f8b0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2f8c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2f8d0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2f8e0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2f8f0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
2f900 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
2f910 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
2f920 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2f930 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2f940 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2f950 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2f960 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2f970 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2f980 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2f990 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2f9a0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2f9b0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
2f9c0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
2f9d0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
2f9e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f9f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
2fa00 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2fa10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2fa20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fa30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
2fa40 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2fa50 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2fa60 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2fa70 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2fa80 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2fa90 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2faa0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2fab0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2fac0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2fad0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2fae0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
2faf0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2fb00 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
2fb10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2fb20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2fb30 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2fb40 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2fb50 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2fb60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2fb70 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2fb80 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2fb90 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2fba0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
2fbb0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2fbc0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2fbd0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2fbe0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2fbf0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2fc00 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2fc10 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2fc20 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2fc30 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2fc40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2fc50 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2fc60 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2fc70 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2fc80 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2fc90 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2fca0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2fcb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fcc0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2fcd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fce0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2fcf0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2fd00 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2fd10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2fd20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2fd30 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
2fd40 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2fd50 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2fd60 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2fd70 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2fd80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2fd90 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2fda0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2fdb0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2fdc0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2fdd0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2fde0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2fdf0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2fe00 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2fe10 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2fe20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2fe30 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2fe40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2fe50 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2fe60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2fe70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2fe80 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2fe90 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2fea0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2feb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2fec0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2fed0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2fee0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2fef0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2ff00 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2ff10 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2ff20 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2ff30 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2ff40 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2ff50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ff60 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2ff70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ff80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2ff90 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2ffa0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2ffb0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2ffc0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2ffd0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2ffe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fff0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
30000 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
30010 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
30020 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
30030 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
30040 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
30050 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
30060 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30070 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
30080 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
30090 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
300a0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
300b0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
300c0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
300d0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
300e0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
300f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
30100 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
30110 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
30120 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
30130 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
30140 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
30150 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
30160 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
30170 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
30180 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
30190 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
301a0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
301b0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
301c0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
301d0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
301e0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
301f0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
30200 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
30210 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
30220 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
30230 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
30240 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
30250 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
30260 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
30270 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
30280 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
30290 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
302a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
302b0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
302c0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
302d0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
302e0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
302f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
30300 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
30310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
30320 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
30330 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
30340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
30350 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
30360 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
30370 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
30380 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
30390 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
303a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
303b0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
303c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
303d0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
303e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
303f0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
30400 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
30410 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
30420 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30430 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
30440 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
30450 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
30460 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
30470 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
30480 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
30490 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
304a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
304b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
304c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
304d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
304e0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
304f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
30500 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
30510 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
30520 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
30530 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
30540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30550 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
30560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
30570 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
30580 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
30590 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
305a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
305b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
305c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
305d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
305e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
305f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30600 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30610 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
30620 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
30630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30640 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
30650 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
30660 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
30670 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
30680 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
30690 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
306a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
306b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
306c0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
306d0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
306e0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
306f0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
30700 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
30710 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
30720 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
30730 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
30740 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
30750 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
30760 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
30770 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30780 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
30790 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
307a0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
307b0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
307c0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
307d0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
307e0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
307f0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
30800 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
30810 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
30820 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
30830 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
30840 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
30850 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
30860 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
30870 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
30880 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
30890 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
308a0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
308b0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
308c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
308d0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
308e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
308f0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
30900 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
30910 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
30920 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
30930 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
30940 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
30950 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
30960 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
30970 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
30980 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
30990 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
309a0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
309b0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
309c0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
309d0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
309e0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
309f0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
30a00 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
30a10 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30a20 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
30a30 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
30a40 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
30a50 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
30a60 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
30a70 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
30a80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
30a90 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
30aa0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
30ab0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
30ac0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
30ad0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
30ae0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
30af0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
30b00 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
30b10 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
30b20 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
30b30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30b40 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
30b50 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
30b60 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
30b70 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
30b80 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
30b90 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
30ba0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
30bb0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
30bc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
30bd0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
30be0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
30bf0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
30c00 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
30c10 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
30c20 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
30c30 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
30c40 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
30c50 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
30c60 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
30c70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30c80 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
30c90 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
30ca0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
30cb0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
30cc0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
30cd0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
30ce0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
30cf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
30d00 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
30d10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
30d20 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
30d30 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
30d40 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
30d50 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
30d60 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
30d70 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
30d80 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
30d90 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
30da0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30db0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
30dc0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
30dd0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
30de0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
30df0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30e00 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
30e10 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
30e20 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
30e30 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
30e40 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
30e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30e60 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
30e70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30e80 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
30e90 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
30ea0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
30eb0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
30ec0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
30ed0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
30ee0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
30ef0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
30f00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30f10 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
30f20 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
30f30 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
30f40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30f50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
30f60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
30f70 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
30f80 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
30f90 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
30fa0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30fb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30fc0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
30fd0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
30fe0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
30ff0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
31000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31010 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
31020 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
31030 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
31040 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
31050 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
31060 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
31070 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
31080 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
31090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
310a0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
310b0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
310c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
310d0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
310e0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
310f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
31100 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
31110 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
31120 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
31130 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
31140 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
31150 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
31160 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
31170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31180 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31190 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
311a0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
311b0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
311c0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
311d0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
311e0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
311f0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
31200 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
31210 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
31220 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
31230 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
31240 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
31250 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31260 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
31270 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
31280 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
31290 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
312a0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
312b0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
312c0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
312d0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
312e0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
312f0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
31300 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
31310 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
31320 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
31330 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
31340 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
31350 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
31360 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
31370 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
31380 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
31390 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
313a0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
313b0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
313c0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
313d0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
313e0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
313f0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
31400 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
31410 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
31420 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
31430 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
31440 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
31450 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
31460 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
31470 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
31480 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
31490 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
314a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
314b0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
314c0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
314d0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
314e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
314f0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
31500 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
31510 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
31520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31530 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
31540 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
31550 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
31560 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
31570 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
31580 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
31590 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
315a0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
315b0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
315c0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
315d0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
315e0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
315f0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
31600 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
31610 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
31620 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
31630 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
31640 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
31650 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
31660 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
31670 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
31680 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
31690 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
316a0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
316b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
316c0 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
316d0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
316e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
316f0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
31700 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
31710 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
31720 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
31730 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
31740 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
31750 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
31760 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
31770 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
31780 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31790 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
317a0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
317b0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
317c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
317d0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
317e0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
317f0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
31800 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
31810 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
31820 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
31830 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
31840 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
31850 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
31860 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
31870 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
31880 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
31890 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
318a0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
318b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
318c0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
318d0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
318e0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
318f0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
31900 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
31910 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
31920 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
31930 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
31940 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
31950 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
31960 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
31970 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
31980 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
31990 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
319a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
319b0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
319c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
319d0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
319e0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
319f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
31a00 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
31a10 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
31a20 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
31a30 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
31a40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
31a50 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
31a60 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
31a70 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
31a80 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
31a90 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
31aa0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
31ab0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
31ac0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
31ad0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
31ae0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
31af0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
31b00 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
31b10 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
31b20 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
31b30 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
31b40 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
31b50 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
31b60 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
31b70 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
31b80 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
31b90 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
31ba0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
31bb0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
31bc0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
31bd0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
31be0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
31bf0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
31c00 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
31c10 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
31c20 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
31c30 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
31c40 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
31c50 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
31c60 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
31c70 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
31c80 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
31c90 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
31ca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
31cb0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
31cc0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
31cd0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
31ce0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
31cf0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
31d00 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
31d10 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
31d20 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
31d30 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
31d40 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
31d50 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
31d60 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
31d70 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
31d80 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
31d90 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
31da0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
31db0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
31dc0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
31dd0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
31de0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
31df0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
31e00 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
31e10 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
31e20 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
31e30 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
31e40 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
31e50 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
31e60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31e70 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
31e80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31e90 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
31ea0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
31eb0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
31ec0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
31ed0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
31ee0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
31ef0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
31f00 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
31f10 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
31f20 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
31f30 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
31f40 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
31f50 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
31f60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
31f70 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
31f80 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
31f90 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
31fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31fb0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
31fc0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
31fd0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
31fe0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31ff0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32000 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
32010 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
32020 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
32030 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32040 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
32050 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
32060 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
32070 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
32080 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32090 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
320a0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
320b0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
320c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
320d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
320e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
320f0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
32100 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
32110 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
32120 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
32130 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
32140 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
32150 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32160 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
32170 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32180 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
32190 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
321a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
321b0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
321c0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
321d0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
321e0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
321f0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
32200 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32210 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32220 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32230 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
32240 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
32250 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
32260 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
32270 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
32280 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
32290 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
322a0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
322b0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
322c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
322d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
322e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
322f0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
32300 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
32310 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
32320 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
32330 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
32340 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
32350 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
32360 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
32370 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
32380 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
32390 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
323a0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
323b0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
323c0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
323d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
323e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
323f0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
32400 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
32410 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
32420 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
32430 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
32440 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
32450 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
32460 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
32470 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
32480 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
32490 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
324a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
324b0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
324c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
324d0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
324e0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
324f0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
32500 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
32510 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
32520 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32530 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
32540 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
32550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32560 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32570 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32580 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
32590 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
325a0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
325b0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
325c0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
325d0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
325e0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
325f0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
32600 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
32610 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
32620 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
32630 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
32640 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32650 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
32660 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
32670 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
32680 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
32690 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
326a0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
326b0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
326c0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
326d0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
326e0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
326f0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
32700 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32710 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
32720 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32730 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
32740 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
32750 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
32760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32770 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
32780 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
32790 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
327a0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
327b0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
327c0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
327d0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
327e0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
327f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32800 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
32810 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
32820 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
32830 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
32840 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
32850 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
32860 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
32870 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32880 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
32890 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
328a0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
328b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
328c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
328d0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
328e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
328f0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
32900 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
32910 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
32920 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
32930 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
32940 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
32950 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
32960 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32970 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32980 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
32990 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
329a0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
329b0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
329c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
329d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
329e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
329f0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
32a00 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
32a10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32a20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32a30 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
32a40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a50 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
32a60 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
32a70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
32a80 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
32a90 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
32aa0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
32ab0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
32ac0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
32ad0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32ae0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32af0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
32b00 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
32b10 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
32b20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
32b30 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32b40 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
32b50 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
32b60 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
32b70 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
32b80 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
32b90 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
32ba0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
32bb0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
32bc0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32bd0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
32be0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
32bf0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
32c00 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
32c10 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
32c20 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
32c30 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
32c40 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
32c50 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
32c60 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
32c70 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
32c80 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
32c90 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
32ca0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
32cb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
32cc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32cd0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
32ce0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
32cf0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
32d00 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
32d10 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
32d20 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
32d30 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
32d40 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
32d50 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
32d60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
32d70 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
32d80 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
32d90 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
32da0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
32db0 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
32dc0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
32dd0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
32de0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
32df0 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
32e00 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
32e10 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
32e20 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
32e30 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
32e40 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
32e50 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
32e60 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
32e70 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
32e80 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
32e90 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
32ea0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
32eb0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
32ec0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
32ed0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
32ee0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
32ef0 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
32f00 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
32f10 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
32f20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
32f30 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
32f40 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
32f50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
32f60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
32f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32f80 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
32f90 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
32fa0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
32fb0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
32fc0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
32fd0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
32fe0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
32ff0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
33000 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
33010 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
33020 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33030 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33040 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
33050 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
33060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33070 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
33080 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
33090 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
330a0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
330b0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
330c0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
330d0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
330e0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
330f0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
33100 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
33110 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
33120 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
33130 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
33140 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
33150 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
33160 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
33170 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33180 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
33190 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
331a0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
331b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
331c0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
331d0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
331e0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
331f0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
33200 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
33210 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
33220 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
33230 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
33240 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
33250 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
33260 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33270 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
33280 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33290 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
332a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
332b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
332c0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
332d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
332e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
332f0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
33300 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33310 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
33320 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
33330 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
33340 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
33350 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
33360 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
33370 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33380 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
33390 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
333a0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
333b0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
333c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
333d0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
333e0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
333f0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
33400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33410 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
33420 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
33430 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
33440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33450 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
33460 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
33470 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
33480 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33490 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
334a0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
334b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
334c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
334d0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
334e0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
334f0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
33500 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
33510 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33520 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33530 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
33540 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
33550 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
33560 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
33570 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
33580 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33590 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
335a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
335b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
335c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
335d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
335e0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
335f0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
33600 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33610 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
33620 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33630 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
33640 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33650 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
33660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33670 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33680 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33690 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
336a0 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
336b0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
336c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
336d0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
336e0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
336f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33700 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
33710 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
33720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33730 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
33740 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
33750 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33760 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
33770 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
33780 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
33790 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
337a0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
337b0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
337c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
337d0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
337e0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
337f0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
33800 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33810 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33820 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
33830 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
33840 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
33850 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33860 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33870 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
33880 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
33890 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
338a0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
338b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
338c0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
338d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
338e0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
338f0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
33900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
33910 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
33920 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
33930 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
33940 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
33950 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
33960 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
33970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
33980 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
33990 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
339a0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
339b0 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
339c0 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
339d0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
339e0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
339f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33a00 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
33a10 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
33a20 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
33a30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
33a40 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
33a50 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
33a60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33a70 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
33a80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33a90 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
33aa0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
33ab0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
33ac0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
33ad0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33ae0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
33af0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
33b00 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
33b10 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
33b20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
33b30 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
33b40 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
33b50 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
33b60 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
33b70 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
33b80 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
33b90 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
33ba0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
33bb0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
33bc0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
33bd0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
33be0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
33bf0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
33c00 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
33c10 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
33c20 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
33c30 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
33c40 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
33c50 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
33c60 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
33c70 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
33c80 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
33c90 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
33ca0 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
33cb0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
33cc0 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
33cd0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
33ce0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
33cf0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
33d00 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
33d10 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
33d20 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
33d30 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
33d40 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
33d50 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
33d60 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
33d70 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
33d80 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
33d90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
33da0 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
33db0 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
33dc0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
33dd0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
33de0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
33df0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
33e00 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
33e10 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
33e20 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
33e30 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
33e40 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
33e50 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
33e60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33e70 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
33e80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33e90 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
33ea0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
33eb0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
33ec0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
33ed0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
33ee0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
33ef0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
33f00 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
33f10 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
33f20 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
33f30 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
33f40 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
33f50 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
33f60 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
33f70 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33f80 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
33f90 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
33fa0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
33fb0 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
33fc0 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
33fd0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
33fe0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
33ff0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
34000 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
34010 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
34020 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
34030 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
34040 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
34050 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
34060 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
34070 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
34080 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
34090 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
340a0 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
340b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
340c0 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
340d0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
340e0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
340f0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
34100 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
34110 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
34120 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
34130 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
34140 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
34150 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
34160 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34170 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
34180 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
34190 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
341a0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
341b0 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
341c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
341d0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
341e0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
341f0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
34200 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
34210 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
34220 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
34230 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
34240 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
34250 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
34260 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
34270 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
34280 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
34290 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
342a0 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
342b0 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
342c0 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
342d0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
342e0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
342f0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
34300 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
34310 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
34320 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
34330 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
34340 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
34350 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
34360 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
34370 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
34380 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
34390 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
343a0 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
343b0 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
343c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
343d0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
343e0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
343f0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
34400 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
34410 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34430 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
34440 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
34450 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34460 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
34470 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
34480 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
34490 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
344a0 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
344b0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
344c0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
344d0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
344e0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
344f0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
34500 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
34510 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
34520 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
34530 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
34540 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
34550 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
34560 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
34570 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
34580 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
34590 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
345a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
345b0 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
345c0 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
345d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
345e0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
345f0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
34600 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
34610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
34620 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34630 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
34640 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
34650 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
34660 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
34670 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
34680 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34690 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
346a0 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
346b0 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
346c0 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
346d0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
346e0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
346f0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
34700 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
34710 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
34720 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
34730 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
34740 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
34750 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
34760 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
34770 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
34780 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
34790 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
347a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
347b0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
347c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
347d0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
347e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
347f0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
34800 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
34810 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
34820 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
34830 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
34840 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
34850 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34860 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34870 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
34880 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34890 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
348a0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
348b0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
348c0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
348d0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
348e0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
348f0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34900 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34910 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
34920 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
34930 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34940 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
34950 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
34960 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
34970 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
34980 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
34990 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
349a0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
349b0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
349c0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
349d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
349e0 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
349f0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
34a00 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
34a10 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
34a20 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
34a30 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
34a40 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
34a50 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
34a60 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
34a70 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
34a80 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
34a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34aa0 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
34ab0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
34ac0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
34ad0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
34ae0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
34af0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
34b00 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
34b10 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
34b20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34b30 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
34b40 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
34b50 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
34b60 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
34b70 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
34b80 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
34b90 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
34ba0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34bb0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
34bc0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
34bd0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
34be0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
34bf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34c00 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
34c10 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
34c20 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
34c30 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
34c40 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
34c50 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
34c60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
34c70 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
34c80 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
34c90 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
34ca0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
34cb0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
34cc0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34cd0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
34ce0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34cf0 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
34d00 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
34d10 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
34d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
34d30 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
34d40 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
34d50 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
34d60 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
34d70 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
34d80 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
34d90 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
34da0 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
34db0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
34dc0 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
34dd0 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
34de0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
34df0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
34e00 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
34e10 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
34e20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
34e30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
34e40 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
34e50 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
34e60 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
34e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34e80 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
34e90 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34ea0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
34eb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34ec0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
34ed0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34ee0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34ef0 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
34f00 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
34f10 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
34f20 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
34f30 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
34f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
34f50 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
34f60 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
34f70 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
34f80 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
34f90 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
34fa0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
34fb0 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
34fc0 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
34fd0 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
34fe0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
34ff0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
35000 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
35010 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
35020 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
35030 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
35040 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
35050 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
35060 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35070 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35080 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
350a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
350b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
350c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
350d0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
350e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
350f0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
35100 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
35110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
35120 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
35130 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
35140 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
35150 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
35160 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
35170 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
35180 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
35190 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
351a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
351b0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
351c0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
351d0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
351e0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
351f0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
35200 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
35210 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
35220 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
35230 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35250 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
35260 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
35270 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
35280 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
35290 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
352a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
352b0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
352c0 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
352d0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
352e0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
352f0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
35300 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
35310 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
35320 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
35330 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
35340 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
35350 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
35360 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
35370 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
35380 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
35390 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
353a0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
353b0 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
353c0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
353d0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
353e0 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
353f0 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
35400 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
35410 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
35420 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
35430 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
35440 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
35450 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
35460 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
35470 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
35480 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
35490 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
354a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
354b0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
354c0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
354d0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
354e0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
354f0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
35500 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
35510 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
35520 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
35530 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
35540 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35550 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
35560 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
35570 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
35580 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
35590 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
355a0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
355b0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
355c0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
355d0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
355e0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
355f0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
35600 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
35610 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
35620 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
35630 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
35640 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
35650 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
35660 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
35670 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
35680 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
35690 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
356a0 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
356b0 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
356c0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
356d0 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
356e0 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
356f0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
35700 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
35710 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
35720 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
35730 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
35740 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
35750 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
35760 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
35770 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
35780 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
35790 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
357a0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
357b0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
357c0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
357d0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
357e0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
357f0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
35800 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
35810 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
35820 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
35830 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
35840 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
35850 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
35860 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
35870 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
35880 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
35890 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
358a0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
358b0 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
358c0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
358d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
358e0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
358f0 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
35900 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
35910 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
35920 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
35930 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
35940 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35950 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35960 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
35970 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
35980 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
35990 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
359a0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
359b0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
359c0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
359d0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
359e0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
359f0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
35a00 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
35a10 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
35a20 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
35a30 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
35a40 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
35a50 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
35a60 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
35a70 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
35a80 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
35a90 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
35aa0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
35ab0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
35ac0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
35ad0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
35ae0 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
35af0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35b00 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
35b10 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
35b20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
35b30 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
35b40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
35b50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
35b60 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
35b70 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
35b80 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35b90 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
35ba0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
35bb0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
35bc0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
35bd0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
35be0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35bf0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
35c00 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
35c10 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
35c20 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
35c30 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
35c40 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
35c50 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
35c60 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
35c70 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
35c80 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
35c90 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
35ca0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
35cb0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
35cc0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
35cd0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
35ce0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
35cf0 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
35d00 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35d10 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
35d20 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ided..**.** <b>N
35d30 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
35d40 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
35d50 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
35d60 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
35d70 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
35d80 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  to calling [sqli
35d90 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71  te3_open] or [sq
35da0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20  lite3_open_v2]. 
35db0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
35dc0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
35dd0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
35de0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
35df0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
35e00 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a  .  Here is an.**
35e10 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20   example of how 
35e20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67  to do this using
35e30 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69   C++ with the Wi
35e40 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a  ndows Runtime:.*
35e50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
35e60 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54  ><pre>.** LPCWST
35e70 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77  R zPath = Window
35e80 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c  s::Storage::Appl
35e90 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72  icationData::Cur
35ea0 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b  rent->.** &nbsp;
35eb0 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f       TemporaryFo
35ec0 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61  lder->Path->Data
35ed0 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74  ();.** char zPat
35ee0 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54  hBuf&#91;MAX_PAT
35ef0 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d  H + 1&#93;;.** m
35f00 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20  emset(zPathBuf, 
35f10 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  0, sizeof(zPathB
35f20 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61  uf));.** WideCha
35f30 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f  rToMultiByte(CP_
35f40 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20  UTF8, 0, zPath, 
35f50 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69  -1, zPathBuf, si
35f60 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a  zeof(zPathBuf),.
35f70 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55  ** &nbsp;     NU
35f80 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71  LL, NULL);.** sq
35f90 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
35fa0 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d  tory = sqlite3_m
35fb0 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61  printf("%s", zPa
35fc0 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65  thBuf);.** </pre
35fd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
35fe0 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
35ff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
36000 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
36010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
36020 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36030 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
36040 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
36050 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
36060 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36070 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36080 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36090 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
360a0 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
360b0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
360c0 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
360d0 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
360e0 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
360f0 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
36100 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
36110 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
36120 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
36130 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
36140 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
36150 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
36160 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
36170 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
36180 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
36190 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
361a0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
361b0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
361c0 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
361d0 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
361e0 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
361f0 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36200 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
36210 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
36220 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
36230 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
36240 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
36250 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
36260 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
36270 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
36280 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
36290 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
362a0 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
362b0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
362c0 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
362d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
362e0 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
362f0 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
36300 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
36310 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
36320 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36330 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
36340 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
36350 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
36360 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
36370 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36380 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36390 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
363a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
363b0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
363c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
363d0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
363e0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
363f0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
36400 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
36410 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
36420 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
36430 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
36440 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
36450 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
36460 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
36470 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
36480 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36490 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
364a0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
364b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
364c0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
364d0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
364e0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
364f0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
36500 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
36510 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
36520 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36530 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
36540 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
36550 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36560 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
36570 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
36580 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
36590 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
365a0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
365b0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
365c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
365d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
365e0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
365f0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
36600 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
36610 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
36620 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
36630 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
36640 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
36650 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
36660 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
36670 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
36680 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
36690 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
366a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
366b0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
366c0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
366d0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
366e0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
366f0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
36700 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
36710 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
36720 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
36730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36740 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
36750 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
36760 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
36770 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
36780 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
36790 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
367a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
367b0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
367c0 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
367d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
367e0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
367f0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
36800 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
36810 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
36820 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
36830 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
36840 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
36850 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
36860 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
36870 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
36880 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
36890 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
368a0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
368b0 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
368c0 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
368d0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
368e0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
368f0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
36900 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
36910 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
36920 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
36930 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
36940 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
36950 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
36960 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
36970 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
36980 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
36990 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
369a0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
369b0 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
369c0 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
369d0 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
369e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
369f0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
36a00 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
36a10 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
36a20 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
36a30 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
36a40 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
36a50 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
36a60 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
36a70 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36a80 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
36a90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
36aa0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
36ab0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
36ac0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
36ad0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36ae0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
36af0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
36b00 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
36b10 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
36b20 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
36b30 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
36b40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
36b50 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
36b60 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
36b70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36b80 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
36b90 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
36ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
36bb0 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
36bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36bd0 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
36be0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
36bf0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
36c00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36c10 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
36c20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
36c30 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
36c40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
36c50 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
36c60 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
36c70 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
36c80 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
36c90 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
36ca0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
36cb0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
36cc0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
36cd0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
36ce0 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
36cf0 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
36d00 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
36d10 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
36d20 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
36d30 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
36d40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
36d50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
36d60 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
36d70 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
36d80 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
36d90 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
36da0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
36db0 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
36dc0 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
36dd0 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
36de0 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
36df0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
36e00 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
36e10 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
36e20 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
36e30 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
36e40 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
36e50 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
36e60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
36e70 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
36e80 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
36e90 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
36ea0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
36eb0 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
36ec0 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
36ed0 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
36ee0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
36ef0 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
36f00 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
36f10 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
36f20 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
36f30 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
36f40 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
36f50 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
36f60 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63  e pathname..*/.c
36f70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
36f80 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
36f90 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
36fa0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
36fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36fc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
36fd0 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
36fe0 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
36ff0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
37000 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
37010 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
37020 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
37030 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
37040 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
37050 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
37060 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
37070 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
37080 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
37090 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
370a0 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ion D..*/.int sq
370b0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
370c0 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
370d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
370e0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
370f0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
37100 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
37110 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
37120 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37130 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37140 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
37150 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37160 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
37170 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
37180 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37190 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
371a0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
371b0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
371c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
371d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
371e0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
371f0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
37200 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
37210 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37220 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
37230 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
37240 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
37250 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
37260 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
37270 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
37280 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
37290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
372a0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
372b0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
372c0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
372d0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
372e0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
372f0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37300 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
37310 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
37320 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37330 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
37340 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
37350 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
37360 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
37370 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
37380 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
37390 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
373a0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
373b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
373c0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
373d0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
373e0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
373f0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
37400 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
37410 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
37420 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
37430 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
37440 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
37450 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
37460 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
37470 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
37480 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
37490 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
374a0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
374b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
374c0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
374d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
374e0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
374f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
37500 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
37510 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
37520 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
37530 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
37540 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
37550 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
37560 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
37570 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37580 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
37590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
375a0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
375b0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
375c0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
375d0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
375e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
375f0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
37600 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
37610 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
37620 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
37630 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
37640 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
37650 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
37660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37670 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
37680 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
37690 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
376a0 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
376b0 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
376c0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
376d0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
376e0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
376f0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
37700 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37710 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
37720 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
37730 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
37740 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
37750 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d  D..**.** The com
37760 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b  mit and rollback
37770 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20   hook callbacks 
37780 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e  are not reentran
37790 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
377a0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
377b0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
377c0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
377d0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
377e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
377f0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
37800 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
37810 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
37820 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
37830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37840 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
37850 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
37860 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
37870 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
37880 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
37890 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
378a0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
378b0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
378c0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
378d0 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69   Note that runni
378e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
378f0 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63   statements, inc
37900 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74  luding SELECT st
37910 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20  atements,.** or 
37920 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b  merely calling [
37930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
37940 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
37950 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
37960 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
37970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37980 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
37990 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
379a0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
379b0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
379c0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
379d0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
379e0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
379f0 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
37a00 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
37a10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37a20 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
37a30 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
37a40 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
37a50 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
37a60 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
37a70 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
37a80 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
37a90 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
37aa0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
37ab0 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
37ac0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
37ad0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
37ae0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
37af0 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
37b00 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
37b10 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
37b20 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
37b30 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
37b40 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
37b50 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
37b60 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
37b70 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
37b80 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
37b90 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
37ba0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
37bb0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
37bc0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
37bd0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
37be0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
37bf0 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
37c00 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
37c10 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
37c20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
37c30 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
37c40 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
37c50 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
37c60 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
37c70 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
37c80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37c90 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
37ca0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
37cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
37cc0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
37cd0 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  rface..*/.void *
37ce0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37cf0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
37d00 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
37d10 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
37d20 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37d30 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
37d40 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
37d50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37d60 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
37d70 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
37d80 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
37d90 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
37da0 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
37db0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
37dc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
37dd0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
37de0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37df0 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
37e00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37e10 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
37e20 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
37e30 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
37e40 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
37e50 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ted..** ^Any cal
37e60 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
37e70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
37e80 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
37e90 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
37ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37eb0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
37ec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
37ed0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
37ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37ef0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
37f00 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
37f10 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
37f20 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
37f30 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
37f40 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
37f50 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
37f60 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
37f70 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
37f80 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37f90 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65  ok()..** ^The se
37fa0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
37fb0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
37fc0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
37fd0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
37fe0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
37ff0 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
38000 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
38010 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
38020 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
38030 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
38040 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
38050 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
38060 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
38070 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
38080 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ers to the.** da
38090 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
380a0 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
380b0 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
380c0 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c  w..** ^The final
380d0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
380e0 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
380f0 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
38100 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f  * ^In the case o
38110 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
38120 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
38130 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
38140 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
38150 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74  *.** ^(The updat
38160 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
38170 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
38180 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
38190 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
381a0 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
381b0 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
381c0 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a  _sequence).)^.**
381d0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72  .** ^In the curr
381e0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
381f0 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68  on, the update h
38200 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e  ook.** is not in
38210 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69  voked when dupli
38220 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20  cation rows are 
38230 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20  deleted because 
38240 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e  of an.** [ON CON
38250 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c  FLICT | ON CONFL
38260 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61  ICT REPLACE] cla
38270 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68  use.  ^Nor is th
38280 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
38290 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f   invoked when ro
382a0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75  ws are deleted u
382b0 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61  sing the [trunca
382c0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
382d0 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69  ..** The excepti
382e0 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74  ons defined in t
382f0 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69  his paragraph mi
38300 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20  ght change in a 
38310 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
38320 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
38330 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
38340 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ok implementatio
38350 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
38360 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
38370 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
38380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38390 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
383a0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
383b0 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
383c0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
383d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
383e0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
383f0 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
38400 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
38410 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
38420 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
38430 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
38440 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a  e update hook..*
38450 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
38460 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
38470 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
38480 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
38490 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
384a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
384b0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
384c0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
384d0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
384e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
384f0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
38500 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a  D,C,P) function.
38510 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ** returns the P
38520 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
38530 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
38540 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
38550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38560 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
38570 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
38580 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a  t call on D..**.
38590 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
385a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
385b0 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c  hook()] and [sql
385c0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
385d0 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ok()].** interfa
385e0 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ces..*/.void *sq
385f0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
38600 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
38610 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
38620 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
38630 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
38640 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
38650 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
38660 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
38670 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
38680 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
38690 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
386a0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
386b0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
386c0 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
386d0 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
386e0 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
386f0 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
38700 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
38710 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74  ection | connect
38720 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ions].** to the 
38730 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53  same database. S
38740 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
38750 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
38760 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64  t is true.** and
38770 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
38780 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c   argument is fal
38790 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63  se.)^.**.** ^Cac
387a0 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
387b0 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
387c0 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ed for an entire
387d0 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
387e0 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
387f0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
38800 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
38810 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
38820 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
38830 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
38840 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled