/ Hex Artifact Content
Login

Artifact ec40aa958a270416fb04b4f72210357bf163d2c5:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  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 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 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 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **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 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5640: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
5670: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5680: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5690: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
56d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5700: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5740: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5750: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5760: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5780: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5840: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
5850: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5860: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5890: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
58a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
58d0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5910: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5930: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5950: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5960: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5990: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
59a0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59b0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59d0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
59e0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
59f0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5a20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5a40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5a60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5aa0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5ab0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ac0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ae0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5af0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5b00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5b30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5b40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5b70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5bc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5bf0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c10: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c30: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c40: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c50: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c70: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c80: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c90: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  ING | (1<<8))../
5ca0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5cb0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5cc0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5cd0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5ce0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5cf0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5d00: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5d10: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5d20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5d30: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5d40: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5d50: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5d60: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5d70: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5d80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5d90: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5da0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5db0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5dc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5dd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5de0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5df0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5e00: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e10: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5e30: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5e40: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5e50: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e60: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e70: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5e80: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5e90: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5ea0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5eb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5ec0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5ed0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5ee0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ef0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5f00: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5f10: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5f20: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f30: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
5f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f50: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5f60: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f70: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5f80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
5f90: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
5fa0: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
5fb0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5fc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5fe0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5ff0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
6000: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6020: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
6030: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
6040: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6050: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
6060: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
6070: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
6080: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
60a0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
60b0: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
60c0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
60d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
60e0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
60f0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
6100: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
6120: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
6130: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
6140: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6150: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
6160: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
6170: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
6180: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6190: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
61a0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
61b0: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
61c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
61d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
61e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
61f0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
6200: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
6210: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6220: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6230: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
6240: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
6250: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
6260: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6270: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6280: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
6290: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
62a0: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
62b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
62c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
62d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
62f0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6300: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6310: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6330: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6340: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6350: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
6360: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
6370: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6380: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
6390: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
63a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
63b0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
63c0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
63d0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
63e0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
63f0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6400: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6410: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6420: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6430: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6440: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6450: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6460: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
6470: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6480: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6490: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
64a0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
64b0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
64c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
64d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
64e0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
64f0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6500: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6510: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6520: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6530: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6540: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6550: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6560: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6570: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6580: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6590: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
65a0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
65b0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
65c0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
65d0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
65e0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
65f0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6600: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6610: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6620: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6630: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6640: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6650: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6660: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6670: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6680: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6690: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
66a0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
66b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
66c0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
66d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66e0: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
66f0: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6700: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6710: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6720: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6730: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6740: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6750: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6760: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6770: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6780: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6790: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
67a0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
67b0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
67c0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   be unchanged..*
67d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
67e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
67f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6800: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6810: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6820: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6830: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6850: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6860: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6870: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
68a0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
68b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68c0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
68d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68e0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
68f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6900: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6910: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6930: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6940: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6950: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6960: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6970: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6980: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6990: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69a0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
69b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
69c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
69e0: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
69f0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6a00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6a10: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6a20: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a40: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6a50: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6a60: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6a80: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6a90: 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a    0x00001000../*
6aa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6ab0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6ac0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6ad0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6ae0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6af0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6b10: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6b20: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6b30: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6b40: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6b50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6b60: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6b70: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6b80: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6ba0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6bb0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6bc0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6bd0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6be0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6bf0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6c10: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6c20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6c30: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6c40: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6c50: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6c60: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6c70: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6c80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6c90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6ca0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6cb0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6cc0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6cd0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6ce0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6cf0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d00: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6d10: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6d20: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6d30: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6d40: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6d50: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6d60: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6d70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6d80: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6d90: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6da0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6db0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6dc0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6dd0: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6de0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6df0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6e00: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6e10: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6e20: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6e30: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6e40: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6e50: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6e60: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6e70: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6e80: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6e90: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6ea0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6eb0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6ec0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6ed0: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6ee0: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6ef0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6f00: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6f10: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6f20: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6f30: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6f40: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6f50: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6f60: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6f70: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
6f80: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
6f90: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6fa0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6fb0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
6fc0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
6fd0: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
6fe0: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
6ff0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7000: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7010: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7020: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7030: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7040: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7050: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7060: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7070: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7080: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7090: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
70a0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
70b0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
70c0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
70d0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
70e0: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
70f0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7100: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7110: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7120: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7130: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7170: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7180: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7190: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
71a0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
71b0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
71c0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
71d0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
71e0: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
71f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7200: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7210: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7230: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7240: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7250: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7260: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7270: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7280: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7290: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
72a0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
72b0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
72c0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
72d0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
72e0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
72f0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7300: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7310: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7320: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7330: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7340: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7350: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7360: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7370: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7380: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
73a0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
73b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
73c0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
73d0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
73e0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
73f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7400: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7410: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7420: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7430: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7440: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7450: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7460: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7480: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7490: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
74a0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
74b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
74c0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
74d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
74e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
74f0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7500: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7510: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7520: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7530: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7540: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7550: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7560: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7570: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7580: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7590: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75a0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
75b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
75c0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
75d0: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
75e0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7600: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7610: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7620: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7630: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7640: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7650: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7660: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7670: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7680: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7690: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
76a0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
76b0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
76c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76d0: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
76e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
76f0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7700: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7710: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7720: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7730: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7740: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7750: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7760: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7770: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7780: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7790: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
77a0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
77b0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
77c0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
77d0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
77e0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
77f0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7800: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7810: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7820: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7830: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7840: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7850: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7860: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7870: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7880: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7890: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
78a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
78b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
78c0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
78d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
78e0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
78f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7900: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7930: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7940: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7950: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7960: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7970: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7980: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7990: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
79a0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
79b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
79c0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
79d0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
79e0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
79f0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7a00: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7a10: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7a20: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7a30: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7a40: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7a50: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7a60: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7a70: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7a80: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7a90: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7aa0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7ab0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7ac0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7ad0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7ae0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7af0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7b00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7b10: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7b20: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7b30: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7b40: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7b50: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7b60: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7b70: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7b80: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7b90: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7ba0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7bb0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7bc0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7bd0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7be0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7bf0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7c00: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7c10: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7c20: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7c30: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7c40: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7c50: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7c60: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7c70: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7c80: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7c90: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7ca0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7cb0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7cc0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7cd0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7ce0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7cf0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7d00: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7d10: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7d20: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
7d30: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
7d40: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d50: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7d60: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7d70: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7d80: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7d90: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7da0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7db0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7dc0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7dd0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7de0: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7df0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e10: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e30: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e40: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7e60: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7e70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7e80: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7e90: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ea0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7eb0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7ec0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7ed0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7ee0: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7ef0: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f00: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f10: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f20: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f30: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f40: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f50: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7f60: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7f70: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7f80: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7f90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fa0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7fb0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
7fc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7fd0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
7fe0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ff0: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8000: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8010: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
8080: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8090: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80b0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
80c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
80d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8100: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8110: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8120: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8130: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8140: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8150: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8160: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8170: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8180: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8190: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81a0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81b0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
81c0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
81d0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
81e0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
81f0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8200: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8210: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8220: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8230: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8240: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8250: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8260: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8270: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8280: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8290: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82a0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82b0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
82c0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
82d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
82e0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
82f0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8300: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8310: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8320: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8330: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8340: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8350: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8360: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8370: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8380: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8390: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83a0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83b0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
83c0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
83d0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
83e0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
83f0: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8400: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8410: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8420: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8430: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8440: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8450: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8460: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8470: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8480: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8490: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84b0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
84c0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
84d0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
84e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
84f0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8500: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8510: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8520: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8530: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8540: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8550: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8560: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8570: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8580: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8590: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85a0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85b0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
85c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
85d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
85e0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
85f0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8600: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8610: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8620: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8640: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8650: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8660: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8670: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8680: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8690: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86a0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
86c0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
86d0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
86f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8700: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8710: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8720: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8730: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8740: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8750: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8760: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8770: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8780: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8790: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87a0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
87c0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
87d0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
87e0: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8800: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8810: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8820: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8830: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8840: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8850: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8860: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8880: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8890: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88a0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88b0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
88d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
88e0: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
88f0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8900: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8910: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8920: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8930: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8940: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8950: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8960: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8970: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8980: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
8990: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
89a0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
89b0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
89c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
89d0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
89e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
89f0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8a00: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8a10: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8a20: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
8a30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8a40: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8a50: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8a60: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8a70: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8a80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8a90: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8aa0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8ab0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8ac0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8ad0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8ae0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8af0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8b00: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8b10: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8b20: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8b30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8b40: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
8b50: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
8b60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8b70: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8b80: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8b90: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8ba0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8bb0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8bc0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8bd0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8be0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8bf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8c00: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8c10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8c20: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8c30: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8c40: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8c50: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8c60: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8c70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8c80: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8c90: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8ca0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8cb0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8cc0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8cd0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8ce0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8cf0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8d00: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8d10: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8d20: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8d30: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8d40: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
8d50: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8d60: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8d70: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8d80: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8d90: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8da0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8db0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8dd0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8de0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8df0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8e00: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
8e10: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
8e20: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
8e30: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
8e40: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
8e50: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
8e60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8e70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8e80: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8e90: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
8ea0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8eb0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8ec0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8ed0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8ee0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8ef0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8f00: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8f10: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
8f20: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
8f30: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
8f40: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
8f50: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
8f60: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
8f70: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8f80: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8f90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8fa0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8fb0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8fc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8fd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8fe0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8ff0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9010: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9020: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
9030: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
9040: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9050: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
9060: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9070: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
9080: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
9090: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
90a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
90b0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
90c0: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
90d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
90e0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
90f0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9100: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
9110: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
9120: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
9130: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
9140: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
9150: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
9160: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9170: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
9180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
9190: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
91a0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
91b0: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
91c0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
91d0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
91e0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
91f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9200: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9210: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
9220: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
9230: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
9240: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
9250: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9260: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9270: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
9280: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
9290: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
92a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
92b0: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
92c0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
92d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
92e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
92f0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
9300: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
9310: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9320: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9330: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9340: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9350: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9360: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
9370: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
9380: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
9390: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
93a0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
93b0: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
93c0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
93d0: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
93e0: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
93f0: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
9400: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
9410: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
9420: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
9430: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9440: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
9450: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
9460: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
9470: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
9480: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
9490: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
94a0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
94b0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
94c0: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
94d0: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
94e0: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
94f0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
9500: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
9510: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
9520: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
9530: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
9540: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
9550: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
9560: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
9570: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
9580: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
9590: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
95a0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
95b0: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
95c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
95d0: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
95e0: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
95f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9600: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9610: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9620: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9630: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
9640: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9650: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9660: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9670: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9680: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9690: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
96a0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
96b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
96c0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
96d0: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
96e0: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
96f0: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9700: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9710: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9720: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9730: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9740: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9750: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9760: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9790: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
97a0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
97b0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
97c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
97d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
97e0: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
97f0: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9800: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
9810: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
9820: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
9830: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
9840: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
9850: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
9860: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
9870: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
9880: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
9890: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
98a0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
98b0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
98c0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
98d0: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
98e0: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
98f0: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9900: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
9910: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
9920: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
9930: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
9940: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
9950: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
9960: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
9970: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
9980: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9990: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
99a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
99b0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
99c0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
99d0: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
99e0: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
99f0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9a00: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
9a10: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9a20: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9a30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9a40: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
9a50: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
9a60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
9a70: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
9a80: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
9a90: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
9aa0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9ab0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9ac0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9ad0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9ae0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9af0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9b00: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9b10: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
9b20: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
9b30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b40: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9b50: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
9b60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9b70: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9b80: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9b90: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9ba0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9bb0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9bc0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9bd0: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9be0: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9bf0: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9c00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
9c10: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
9c20: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
9c30: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
9c40: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
9c50: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
9c60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9c70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9c80: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9c90: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9ca0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9cb0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9cc0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9cd0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9ce0: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9cf0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9d00: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
9d10: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9d20: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9d30: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9d40: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9d50: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
9d60: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
9d70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9d80: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9da0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9db0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9dc0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9dd0: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9de0: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9df0: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9e00: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
9e10: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
9e20: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
9e30: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
9e40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
9e50: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
9e60: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
9e70: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
9e80: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
9e90: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
9ea0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9ec0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9ed0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9ee0: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9ef0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9f00: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
9f10: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
9f20: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
9f30: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
9f40: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
9f50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
9f60: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
9f70: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
9f80: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
9f90: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
9fa0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9fb0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9fc0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9fd0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9fe0: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9ff0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a020: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a030: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a040: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a050: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a060: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a070: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a080: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a090: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a0a0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a0b0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a0c0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a0d0: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a0e0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a0f0: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a100: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a110: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a120: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a130: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a140: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a150: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a160: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
a170: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a190: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
a1a0: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
a1b0: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
a1c0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
a1e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
a1f0: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
a200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
a210: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
a220: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
a230: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
a240: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
a250: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
a260: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
a270: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
a280: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a290: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
a2a0: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
a2b0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
a2c0: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
a2d0: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
a2e0: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
a2f0: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
a300: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
a310: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
a320: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
a330: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
a340: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
a350: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
a360: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
a370: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
a380: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
a390: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a3a0: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
a3b0: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
a3c0: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
a3d0: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
a3e0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
a3f0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
a400: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
a410: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
a420: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
a430: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
a440: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
a450: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
a460: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
a470: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
a480: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
a490: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
a4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a4b0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a4c0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
a4d0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
a4e0: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
a4f0: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
a500: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
a510: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a520: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
a530: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
a540: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
a550: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
a560: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
a570: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
a580: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
a590: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
a5a0: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
a5b0: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
a5c0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
a5d0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a5e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a5f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a600: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
a610: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
a620: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
a630: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a640: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
a650: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
a660: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a670: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a680: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a690: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a6a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a6b0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a6c0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a6d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a6e0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a6f0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a700: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a710: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a720: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a730: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a740: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a750: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a760: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
a770: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a780: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
a790: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a7a0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
a7b0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
a7c0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
a7d0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
a7e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a7f0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
a800: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
a810: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
a820: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
a830: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
a840: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
a850: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
a860: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
a870: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a880: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
a890: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
a8a0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
a8b0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
a8c0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
a8d0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
a8e0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
a8f0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
a900: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
a910: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
a920: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
a930: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
a940: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
a950: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
a960: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
a970: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
a980: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
a990: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
a9a0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
a9b0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
a9c0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
a9d0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
a9e0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
a9f0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
aa00: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
aa10: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
aa20: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
aa30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa40: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
aa50: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
aa60: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
aa70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
aa80: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
aa90: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
aaa0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
aab0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
aac0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
aad0: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
aae0: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
aaf0: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
ab00: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ab10: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
ab20: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
ab30: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
ab40: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
ab50: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
ab60: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
ab70: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
ab80: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
ab90: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
aba0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
abb0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
abc0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
abd0: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
abe0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
abf0: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
ac00: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
ac10: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
ac20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ac30: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
ac40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ac50: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
ac60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
ac70: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
ac80: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
ac90: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
aca0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
acb0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
acc0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
acd0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
ace0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
acf0: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
ad00: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
ad10: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
ad20: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
ad30: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
ad40: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
ad50: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
ad60: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
ad70: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
ad80: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
ad90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
ada0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
adb0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
adc0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
add0: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
ade0: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
adf0: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
ae00: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
ae10: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
ae20: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
ae30: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
ae40: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
ae50: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
ae60: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
ae70: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c  ize]..**.** </ul
ae80: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
ae90: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
aea0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
aeb0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
aec0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
aed0: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
aee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
aef0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
af00: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
af10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
af20: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
af30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
af40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
af50: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
af60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
af70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
af80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
af90: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
afa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
afb0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
afd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
afe0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
aff0: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
b000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b010: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
b020: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
b030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b040: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
b050: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
b060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b070: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
b080: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
b090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
b0a0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
b0b0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
b0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
b0d0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
b0e0: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
b0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b100: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
b110: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
b120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b130: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
b140: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
b150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b160: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
b170: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
b180: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b190: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
b1a0: 20 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   18../*.** CAPI3
b1b0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
b1c0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
b1d0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
b1e0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
b1f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
b200: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
b210: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
b220: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
b230: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
b240: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
b250: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
b260: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
b270: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
b280: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
b290: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
b2a0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
b2b0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
b2c0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
b2d0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
b2e0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
b2f0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
b300: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b310: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
b320: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
b330: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
b340: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
b350: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
b360: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
b370: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
b380: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
b390: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
b3a0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
b3b0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
b3c0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
b3d0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
b3e0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
b3f0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
b400: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
b410: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
b420: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
b430: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
b440: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
b450: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
b460: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
b470: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
b480: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
b490: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
b4a0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
b4b0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
b4c0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
b4d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
b4e0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
b4f0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
b500: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
b510: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
b520: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
b530: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
b540: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
b550: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
b560: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
b570: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
b580: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
b590: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
b5a0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
b5b0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
b5c0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
b5d0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
b5e0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
b5f0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
b600: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
b610: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
b620: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
b630: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
b640: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
b650: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
b660: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
b670: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
b680: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b690: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
b6a0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
b6b0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
b6c0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
b6d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
b6e0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
b6f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
b700: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
b710: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
b720: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
b730: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
b740: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
b750: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
b760: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
b770: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
b780: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
b790: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
b7a0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
b7b0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
b7c0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
b7d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
b7e0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
b7f0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
b800: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
b810: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
b820: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
b830: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
b840: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
b850: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
b860: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
b870: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
b880: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
b890: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
b8a0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
b8b0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
b8c0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
b8d0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
b8e0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
b8f0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
b900: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
b910: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
b920: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
b930: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
b940: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
b950: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
b960: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
b970: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
b980: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b990: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
b9a0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
b9b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
b9c0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
b9d0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
b9e0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
b9f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
ba00: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
ba10: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
ba20: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
ba30: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
ba40: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
ba50: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ba60: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
ba70: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
ba80: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
ba90: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
baa0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
bab0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
bac0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
bad0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
bae0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
baf0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
bb00: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
bb10: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
bb20: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
bb30: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
bb40: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
bb50: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
bb60: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
bb70: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
bb80: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
bb90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
bba0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
bbb0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
bbc0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
bbd0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
bbe0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
bbf0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
bc00: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
bc10: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
bc20: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
bc30: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
bc40: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
bc50: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
bc60: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
bc70: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
bc80: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
bc90: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
bca0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
bcb0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
bcc0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
bcd0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
bce0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
bcf0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
bd00: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
bd10: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
bd20: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
bd30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
bd40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
bd50: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
bd60: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
bd70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
bd80: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
bd90: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
bda0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
bdb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
bdc0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
bdd0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
bde0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
bdf0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
be00: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
be10: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
be20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
be30: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
be40: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
be50: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
be60: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
be70: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
be80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
be90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
bea0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
beb0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
bec0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
bed0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
bee0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
bef0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
bf00: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
bf10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
bf20: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
bf30: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
bf40: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
bf50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
bf60: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
bf70: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
bf80: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
bf90: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bfa0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
bfb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
bfc0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
bfd0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
bfe0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
bff0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
c000: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
c010: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c020: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
c030: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
c040: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
c050: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
c060: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
c070: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
c080: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
c090: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
c0a0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
c0b0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
c0c0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
c0d0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
c0e0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
c0f0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
c100: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
c110: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
c120: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
c130: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
c140: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
c150: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
c160: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
c170: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
c180: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
c190: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
c1a0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
c1b0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
c1c0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
c1d0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
c1e0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
c1f0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
c200: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
c210: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
c220: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
c230: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c240: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c250: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
c260: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c270: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
c280: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
c290: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
c2a0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
c2b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
c2c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
c2d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
c2e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
c2f0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
c300: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
c310: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
c320: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c330: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
c340: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
c350: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
c360: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
c370: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
c380: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
c390: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
c3a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
c3b0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
c3c0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
c3d0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
c3e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
c3f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
c400: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
c410: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
c420: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
c430: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
c440: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
c450: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
c460: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
c470: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
c480: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
c490: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
c4a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
c4b0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
c4c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
c4d0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
c4e0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
c4f0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
c500: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
c510: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
c520: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
c530: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
c540: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
c550: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
c560: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
c570: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
c580: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
c590: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
c5a0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
c5b0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
c5c0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
c5d0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
c5e0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
c5f0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
c600: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
c610: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
c620: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
c630: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
c640: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
c650: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
c660: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
c670: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
c680: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
c690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
c6a0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
c6b0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
c6c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
c6d0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
c6e0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
c6f0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
c700: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
c710: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
c720: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
c730: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
c740: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
c750: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
c760: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
c770: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
c780: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
c790: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
c7a0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
c7b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
c7c0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
c7d0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c7e0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
c7f0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
c800: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
c810: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
c820: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
c830: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
c840: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
c850: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
c860: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
c870: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
c880: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
c890: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
c8a0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c8b0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
c8c0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
c8d0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
c8e0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
c8f0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
c900: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
c910: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
c920: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
c930: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
c940: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
c950: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
c960: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
c970: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
c980: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
c990: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
c9a0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
c9b0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
c9c0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
c9d0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
c9e0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
c9f0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
ca00: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
ca10: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
ca20: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
ca30: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
ca40: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
ca50: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
ca60: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
ca70: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
ca80: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
ca90: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
caa0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
cab0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
cac0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
cad0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
cae0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
caf0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
cb00: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
cb10: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
cb20: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
cb30: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
cb40: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
cb50: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
cb60: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
cb70: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
cb80: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
cb90: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
cba0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
cbb0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
cbc0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
cbd0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
cbe0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
cbf0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
cc00: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
cc10: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
cc20: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
cc30: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
cc40: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
cc50: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
cc60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
cc70: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
cc80: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
cc90: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
cca0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
ccb0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
ccc0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
ccd0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
cce0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
ccf0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
cd00: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
cd10: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
cd20: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
cd30: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
cd40: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
cd50: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
cd60: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
cd70: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
cd80: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
cd90: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
cda0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
cdb0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
cdc0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
cdd0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
cde0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
cdf0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
ce00: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
ce10: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
ce20: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
ce30: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
ce40: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
ce50: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
ce60: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
ce70: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
ce80: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
ce90: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
cea0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
ceb0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
cec0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
ced0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
cee0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
cef0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
cf00: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
cf10: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
cf20: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
cf30: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
cf40: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
cf50: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
cf60: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
cf70: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
cf80: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
cf90: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
cfa0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
cfb0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
cfc0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
cfd0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
cfe0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
cff0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
d000: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
d010: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
d020: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
d030: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
d040: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
d050: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
d060: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
d070: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
d080: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
d090: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
d0a0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
d0b0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
d0c0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
d0d0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
d0e0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
d0f0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
d100: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
d110: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
d120: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
d130: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
d140: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
d150: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
d160: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
d170: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
d180: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
d190: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
d1a0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
d1b0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
d1c0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
d1d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
d1e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
d1f0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
d200: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
d210: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
d220: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
d230: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
d240: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
d250: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
d260: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
d270: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
d280: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
d290: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
d2a0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
d2b0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
d2c0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
d2d0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
d2e0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
d2f0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
d300: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
d310: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
d320: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
d330: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
d340: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
d350: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
d360: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
d370: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
d380: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d390: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
d3a0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
d3b0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
d3c0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
d3d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
d3e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
d3f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
d400: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
d410: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
d420: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
d430: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
d440: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d450: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
d460: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
d470: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
d480: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d490: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
d4a0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
d4b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
d4c0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
d4d0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d4e0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
d4f0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
d500: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
d510: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
d520: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d530: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
d540: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
d550: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
d560: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
d570: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
d580: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
d590: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
d5a0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
d5b0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
d5c0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
d5d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
d5e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
d5f0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
d600: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
d610: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d620: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
d630: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d640: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
d650: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d660: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
d670: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
d680: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
d690: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
d6a0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
d6b0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
d6c0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
d6d0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
d6e0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d6f0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
d700: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
d710: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
d720: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
d730: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
d740: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d750: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
d760: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
d770: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
d780: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d790: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d7a0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
d7b0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d7c0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
d7d0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
d7e0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
d7f0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
d800: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
d810: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d820: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d830: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
d840: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
d850: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d860: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
d870: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d880: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d890: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
d8a0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
d8b0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d8c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d8d0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
d8e0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d8f0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d900: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
d910: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d920: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d930: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
d940: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
d950: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
d960: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
d970: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
d980: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
d990: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
d9a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
d9b0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
d9c0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
d9d0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d9e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d9f0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
da00: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
da10: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
da20: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
da30: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
da40: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
da50: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
da60: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
da70: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
da80: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
da90: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
daa0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
dab0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
dac0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
dad0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
dae0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
daf0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
db00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
db10: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
db20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
db30: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
db40: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
db50: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
db60: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
db70: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
db80: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
db90: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
dba0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
dbb0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
dbc0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
dbd0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
dbe0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
dbf0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
dc00: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
dc10: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
dc20: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
dc30: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
dc40: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
dc50: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
dc60: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
dc70: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
dc80: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
dc90: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
dca0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
dcb0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
dcc0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
dcd0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
dce0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
dcf0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
dd00: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
dd10: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
dd20: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
dd30: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
dd40: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
dd50: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
dd60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
dd70: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
dd80: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
dd90: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
dda0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
ddb0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ddc0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
ddd0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
dde0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ddf0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
de00: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
de10: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
de20: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
de30: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
de40: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
de50: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
de60: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
de70: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
de80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
de90: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
dea0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
deb0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
dec0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
ded0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
dee0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
def0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
df00: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
df10: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
df20: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
df30: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
df40: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
df50: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
df60: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
df70: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
df80: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
df90: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
dfa0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
dfb0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
dfc0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
dfd0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
dfe0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
dff0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
e000: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
e010: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
e020: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
e030: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
e040: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
e050: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
e060: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
e070: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
e080: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
e090: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
e0a0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
e0b0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
e0c0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
e0d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e0e0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
e0f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
e100: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
e110: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
e120: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
e130: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
e140: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
e150: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
e160: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
e170: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
e180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
e190: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
e1a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
e1b0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
e1c0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
e1d0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
e1e0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
e1f0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
e200: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
e210: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
e220: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
e230: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
e240: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
e250: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
e260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e270: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
e280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e290: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
e2a0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
e2b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
e2c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
e2d0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
e2e0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
e2f0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
e300: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e310: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
e320: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
e330: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
e340: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
e350: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e360: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
e370: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
e380: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
e390: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
e3a0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
e3b0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
e3c0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
e3d0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
e3e0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
e3f0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
e400: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
e410: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
e420: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
e430: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
e440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e450: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
e460: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
e470: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
e480: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
e490: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
e4a0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
e4b0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
e4c0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
e4d0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
e4e0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
e4f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
e500: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
e510: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
e520: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
e530: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
e540: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
e550: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e560: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
e570: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
e580: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
e590: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
e5a0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e5b0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e5c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
e5d0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
e5e0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
e5f0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
e600: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e610: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
e620: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
e630: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
e640: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
e650: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
e660: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
e670: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
e680: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
e690: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
e6a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e6b0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
e6c0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
e6d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e6e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
e6f0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
e700: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
e710: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
e720: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
e730: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e740: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
e750: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
e760: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
e770: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
e780: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e790: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
e7a0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
e7b0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
e7c0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
e7d0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
e7e0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
e7f0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
e800: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
e810: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
e820: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
e830: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
e840: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
e850: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
e860: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
e870: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
e880: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
e890: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
e8a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e8b0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
e8c0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
e8d0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
e8e0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
e8f0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
e900: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e910: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
e920: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
e930: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
e940: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
e950: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
e960: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
e970: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
e980: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
e990: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
e9a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
e9b0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
e9c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e9d0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
e9e0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
e9f0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
ea00: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
ea10: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
ea20: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
ea30: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
ea40: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
ea50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ea60: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
ea70: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
ea80: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
ea90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eaa0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
eab0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
eac0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
ead0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
eae0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
eaf0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
eb00: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
eb10: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
eb20: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
eb30: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
eb40: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
eb50: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
eb60: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
eb70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
eb80: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
eb90: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
eba0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ebb0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
ebc0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
ebd0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
ebe0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ebf0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
ec00: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
ec10: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
ec20: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
ec30: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
ec40: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
ec50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
ec60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
ec70: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
ec80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ec90: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
eca0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
ecb0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
ecc0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
ecd0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
ece0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
ecf0: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
ed00: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
ed10: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
ed20: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
ed30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
ed40: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
ed50: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
ed60: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
ed70: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
ed80: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
ed90: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
eda0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
edb0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
edc0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
edd0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
ede0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
edf0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
ee00: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
ee10: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
ee20: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
ee30: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
ee40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ee50: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
ee60: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
ee70: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
ee80: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
ee90: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
eea0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
eeb0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
eec0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
eed0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
eee0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
eef0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
ef00: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
ef10: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
ef20: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
ef30: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
ef40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
ef50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
ef60: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
ef70: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
ef80: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ef90: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
efa0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
efb0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
efc0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
efd0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
efe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eff0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
f000: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
f010: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f020: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
f030: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
f040: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
f050: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f060: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
f070: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
f080: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
f090: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
f0a0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
f0b0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
f0c0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
f0d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f0e0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
f0f0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
f100: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
f110: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
f120: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
f130: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
f140: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
f150: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
f160: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
f170: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
f180: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
f190: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
f1a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
f1b0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
f1c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
f1d0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
f1e0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
f1f0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
f200: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
f210: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
f220: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
f230: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
f240: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f250: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
f260: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
f270: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
f280: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
f290: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
f2a0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
f2b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
f2c0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
f2d0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
f2e0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
f2f0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
f300: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
f310: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
f320: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
f330: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
f340: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
f350: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f360: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
f370: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
f380: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
f390: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
f3a0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f3b0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
f3c0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
f3d0: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
f3e0: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
f3f0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
f400: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
f410: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
f420: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
f430: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
f440: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
f450: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
f460: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
f470: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
f480: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
f490: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
f4a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f4b0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
f4c0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
f4d0: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
f4e0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
f4f0: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
f500: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f510: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
f520: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
f530: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
f540: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
f550: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
f560: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
f570: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
f580: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
f590: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
f5a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f5b0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
f5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
f5d0: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
f5e0: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
f5f0: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
f600: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
f610: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
f620: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
f630: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
f640: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
f650: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
f660: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
f670: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
f680: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
f690: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
f6a0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
f6b0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
f6c0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
f6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
f6e0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
f6f0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
f700: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
f710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f720: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
f730: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
f740: 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
f750: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
f760: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
f770: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
f780: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
f790: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
f7a0: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
f7b0: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
f7c0: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
f7d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f7e0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
f7f0: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
f800: 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
f810: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
f820: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
f830: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
f840: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
f850: 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
f860: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
f870: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
f880: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
f890: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
f8a0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
f8b0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
f8c0: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
f8d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
f8e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
f8f0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
f900: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f910: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
f920: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
f930: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
f940: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
f950: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
f960: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
f970: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f980: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
f990: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
f9a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f9b0: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
f9c0: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
f9d0: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
f9e0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
f9f0: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
fa00: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
fa10: 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
fa20: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
fa30: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
fa40: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
fa50: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
fa60: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
fa70: 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
fa80: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
fa90: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
faa0: 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
fab0: 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
fac0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
fad0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
fae0: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
faf0: 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
fb00: 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
fb10: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
fb20: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
fb30: 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
fb40: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
fb50: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
fb60: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
fb70: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
fb80: 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
fb90: 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
fba0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
fbb0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
fbc0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
fbd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fbe0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
fbf0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
fc00: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
fc10: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
fc20: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
fc30: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
fc40: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
fc50: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
fc60: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
fc70: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
fc80: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
fc90: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
fca0: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
fcb0: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
fcc0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
fcd0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
fce0: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
fcf0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
fd00: 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
fd10: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
fd20: 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
fd30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
fd40: 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
fd50: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
fd60: 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
fd70: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
fd80: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
fd90: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
fda0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
fdb0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
fdc0: 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
fdd0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
fde0: 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
fdf0: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
fe00: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
fe10: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
fe20: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
fe30: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
fe40: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
fe50: 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
fe60: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
fe70: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
fe80: 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
fe90: 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
fea0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
feb0: 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
fec0: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
fed0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
fee0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
fef0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
ff00: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
ff10: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
ff20: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
ff30: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
ff40: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
ff50: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
ff60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
ff70: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
ff80: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
ff90: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
ffa0: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
ffb0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
ffc0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
ffd0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
ffe0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
fff0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
10000 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
10010 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
10020 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
10030 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
10040 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
10050 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
10060 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
10070 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
10080 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
10090 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
100a0 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
100b0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
100c0 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
100d0 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
100e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
100f0 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
10100 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
10110 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10120 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
10130 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
10140 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
10150 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
10160 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
10170 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
10180 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
10190 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
101a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
101b0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
101c0 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
101d0 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
101e0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
101f0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
10200 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
10210 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
10220 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
10230 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
10240 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
10250 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
10260 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
10270 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
10280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10290 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
102a0 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
102b0 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
102c0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
102d0 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
102e0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
102f0 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
10300 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
10310 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
10320 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
10330 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
10340 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
10350 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
10360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10370 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
10380 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
10390 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
103a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
103b0 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
103c0 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
103d0 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
103e0 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
103f0 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
10400 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
10410 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
10420 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
10430 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
10440 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
10450 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f   allocator.  (Fo
10460 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
10470 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
10480 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
10490 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
104a0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
104b0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
104c0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
104d0 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
104e0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
104f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
10500 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
10510 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
10520 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
10530 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
10540 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10550 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10560 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10570 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10580 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10590 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
105a0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
105b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
105c0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
105d0 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
105e0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
105f0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
10600 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10610 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10620 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10630 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10640 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10650 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10660 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10670 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10680 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10690 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
106a0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
106b0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
106c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
106d0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
106e0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
106f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10700 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10710 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10720 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10730 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10740 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10750 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
10760 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
10770 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
10780 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
10790 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
107a0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
107b0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
107c0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
107d0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
107e0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
107f0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
10800 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
10810 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
10820 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
10830 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
10840 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
10850 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
10860 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
10870 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
10880 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
10890 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
108a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
108b0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
108c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
108d0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
108e0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
108f0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
10900 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
10910 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
10920 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10930 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
10940 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
10950 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
10960 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
10970 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
10980 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
10990 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
109a0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
109b0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
109c0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
109d0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
109e0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
109f0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
10a00 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
10a10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
10a20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
10a30 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
10a40 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
10a50 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
10a60 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
10a70 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
10a80 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
10a90 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
10aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10ab0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
10ac0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
10ad0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
10ae0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
10af0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
10b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10b10 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
10b20 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
10b30 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
10b40 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
10b50 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
10b60 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
10b70 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
10b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10b90 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
10ba0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
10bb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10bc0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
10bd0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
10be0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
10bf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10c00 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
10c10 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
10c20 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
10c30 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
10c40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10c50 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
10c60 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
10c70 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
10c80 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
10c90 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
10ca0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
10cb0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
10cc0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
10cd0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
10ce0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
10cf0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
10d00 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
10d10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
10d20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
10d30 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
10d40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10d50 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
10d60 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
10d70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10d80 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
10d90 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10da0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
10db0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10dc0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10dd0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10de0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10df0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10e00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
10e10 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
10e20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
10e30 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
10e40 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
10e50 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
10e60 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
10e70 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
10e80 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
10e90 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
10ea0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10eb0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
10ec0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
10ed0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
10ee0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
10ef0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
10f00 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
10f10 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
10f20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
10f30 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
10f40 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
10f50 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
10f60 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
10f70 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10f80 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
10f90 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
10fa0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
10fb0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10fc0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
10fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
10fe0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11000 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
11010 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11020 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11030 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11040 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11050 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11060 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11070 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11080 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
11090 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
110a0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
110b0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
110c0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
110d0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
110e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
110f0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
11100 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
11110 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
11120 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
11130 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
11140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11150 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11160 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
11170 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
11180 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
11190 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
111a0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
111b0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
111c0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
111d0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
111e0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
111f0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
11200 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
11210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
11220 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
11230 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11240 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11250 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11260 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11270 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11280 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11290 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
112a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
112b0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
112c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
112d0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
112e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
112f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11300 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11310 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
11320 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11330 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
11340 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11350 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11370 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
11380 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11390 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
113a0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
113b0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
113c0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
113d0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
113e0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
113f0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
11400 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
11410 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
11420 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
11430 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
11440 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
11450 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
11460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11470 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11480 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11490 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
114a0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
114b0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
114c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
114d0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
114e0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
114f0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11500 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
11510 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
11520 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
11530 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11540 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11550 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11560 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11570 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11580 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
115a0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
115b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
115c0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
115d0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
115e0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
115f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11600 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11610 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11620 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11630 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11640 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11650 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11660 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11670 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11680 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11690 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
116a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
116b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
116c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
116d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
116e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
116f0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
11700 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11710 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11720 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11730 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11740 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11750 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11760 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11770 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11780 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11790 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
117a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
117b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
117c0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
117d0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
117e0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
117f0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
11800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11810 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
11820 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
11830 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11840 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
11850 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
11860 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
11870 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
11880 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
11890 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
118a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
118b0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
118c0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
118d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
118e0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
118f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11900 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11910 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
11920 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11930 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11940 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11950 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11960 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11970 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11980 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11990 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
119a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
119b0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
119c0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
119d0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
119e0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
119f0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
11a00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11a10 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
11a20 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
11a30 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
11a40 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
11a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
11a70 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
11a80 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
11a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11aa0 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
11ab0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
11ac0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
11ad0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11af0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
11b00 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11b10 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
11b20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
11b30 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
11b40 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
11b50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
11b60 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
11b70 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
11b80 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
11b90 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
11ba0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
11bb0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
11bc0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
11bd0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11be0 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
11bf0 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
11c00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11c10 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
11c20 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
11c30 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
11c40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
11c50 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
11c60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
11c70 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
11c80 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11c90 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
11ca0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
11cb0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
11cc0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
11cd0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
11ce0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11cf0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
11d00 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
11d10 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
11d20 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
11d30 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
11d40 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
11d50 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
11d60 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
11d70 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
11d80 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
11d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
11db0 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
11dc0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
11dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11de0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
11df0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
11e00 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11e10 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
11e20 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
11e30 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
11e40 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
11e50 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20  :  A pointer an 
11e60 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
11e70 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
11e80 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73  from which the s
11e90 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11ea0 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
11eb0 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
11ec0 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
11ed0 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
11ee0 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
11ef0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
11f00 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
11f10 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
11f20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11f30 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
11f40 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
11f50 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11f60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11f70 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
11f80 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
11f90 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
11fa0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
11fb0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
11fc0 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
11fd0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
11fe0 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
11ff0 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
12000 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
12010 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
12020 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
12030 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
12040 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
12050 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
12060 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
12070 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
12080 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
12090 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
120a0 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
120b0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
120c0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
120d0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
120e0 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
120f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12100 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
12110 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
12120 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
12130 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
12140 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
12150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12160 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
12170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12180 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
12190 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
121a0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
121b0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
121c0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
121d0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
121e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
121f0 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
12200 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
12210 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12220 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
12230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
12240 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
12250 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
12260 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
12270 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
12280 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
12290 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
122a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
122b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
122c0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
122d0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
122e0 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
122f0 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
12300 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
12310 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
12320 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
12330 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
12340 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
12350 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
12360 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
12370 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
12380 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
12390 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
123a0 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
123b0 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
123c0 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
123d0 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
123e0 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
123f0 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
12400 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
12410 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
12420 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
12430 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
12440 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
12450 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
12460 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
12470 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
12480 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
12490 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
124a0 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
124b0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
124c0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
124d0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
124e0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
124f0 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
12500 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
12510 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12520 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
12530 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
12540 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
12550 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
12560 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
12570 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
12580 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
12590 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
125a0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
125b0 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
125c0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
125d0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
125e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
125f0 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
12600 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
12610 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
12620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12630 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
12640 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12650 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
12660 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12670 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
12680 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
12690 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
126b0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
126c0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
126d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
126e0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
126f0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12700 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12710 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
12720 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
12730 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
12740 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
12750 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
12760 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
12770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12780 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
12790 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
127a0 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
127b0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
127c0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
127d0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
127e0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
127f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
12800 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
12810 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
12820 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
12830 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
12840 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
12850 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
12860 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
12870 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
12880 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
12890 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
128a0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
128b0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
128c0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
128d0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
128e0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
128f0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
12900 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
12910 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
12920 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
12930 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
12940 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
12950 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
12960 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12970 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
12980 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
12990 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
129a0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
129b0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
129c0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
129d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
129e0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
129f0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12a00 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12a10 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
12a20 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
12a30 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
12a40 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
12a50 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
12a60 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
12a70 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
12a80 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
12a90 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
12aa0 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
12ab0 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
12ac0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
12ad0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
12ae0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
12af0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12b00 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
12b10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12b20 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
12b30 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12b40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12b50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12b60 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12b70 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12b80 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12b90 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12ba0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12bb0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12bc0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12bd0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
12be0 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
12bf0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
12c00 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
12c10 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12c20 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
12c30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12c40 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
12c50 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12c60 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12c70 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
12c80 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
12c90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12ca0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
12cb0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12cc0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12cd0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12ce0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12cf0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12d00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12d10 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
12d20 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
12d30 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
12d40 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
12d50 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
12d60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12d70 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
12d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12d90 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
12da0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
12db0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
12dc0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
12dd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12de0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
12df0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12e00 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
12e10 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12e20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12e30 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12e40 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12e50 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12e60 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12e70 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12e80 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12e90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
12ea0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
12eb0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12ec0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12ed0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
12ee0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
12ef0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
12f00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
12f10 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12f20 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
12f30 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
12f40 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
12f50 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
12f60 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
12f70 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
12f80 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
12f90 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
12fa0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12fb0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12fc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12fd0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12fe0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12ff0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13000 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
13010 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
13020 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
13030 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
13040 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
13050 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
13060 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
13070 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
13080 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
13090 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
130a0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
130b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
130c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
130d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
130e0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
130f0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13100 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
13110 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13120 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
13130 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
13140 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
13150 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13160 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69   for the lookasi
13170 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
13180 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b  tor on each.** [
13190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
131a0 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ion].  The first
131b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
131c0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
131d0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
131e0 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
131f0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
13200 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
13210 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
13220 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
13230 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73  ction.)^  ^(This
13240 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13250 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  .** <i>default</
13260 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
13270 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
13280 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
13290 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73  E].** verb to [s
132a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
132b0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
132c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
132d0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
132e0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
132f0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
13300 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
13310 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13320 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
13330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13340 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
13350 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13360 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13370 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13380 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
13390 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
133a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
133b0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
133c0 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
133d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
133e0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
133f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13400 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
13410 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
13420 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
13430 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
13440 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13450 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
13460 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13470 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13480 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13490 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
134a0 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
134b0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
134c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
134d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
134e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
134f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
13500 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13510 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
13520 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
13530 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
13540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13550 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
13560 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13570 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13580 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
13590 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
135a0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
135b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
135c0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
135d0 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
135e0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
135f0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
13600 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13610 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
13620 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13630 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
13640 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
13650 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
13660 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
13670 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
13680 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
13690 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
136a0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
136b0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
136c0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
136d0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
136e0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
136f0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
13700 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13710 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
13720 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
13730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
13740 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
13750 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
13760 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
13770 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
13780 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13790 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
137a0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
137b0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
137c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
137d0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
137e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
137f0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
13800 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
13810 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
13820 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
13830 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
13840 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
13850 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
13860 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13870 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
13880 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
13890 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
138a0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
138b0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
138c0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
138d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
138e0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
138f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
13900 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
13910 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
13920 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
13930 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
13940 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
13950 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
13960 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
13970 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
13980 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
13990 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
139a0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
139b0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
139c0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
139d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
139e0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
139f0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
13a00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13a10 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13a20 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
13a30 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
13a40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13a50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
13a60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13a70 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
13a80 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13a90 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13aa0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
13ab0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
13ac0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
13ad0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
13ae0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
13af0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
13b00 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
13b10 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
13b20 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
13b30 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13b40 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
13b50 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
13b60 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
13b70 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
13b80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
13b90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13ba0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
13bb0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
13bc0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
13bd0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
13be0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
13bf0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
13c00 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
13c10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
13c20 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
13c30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
13c40 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
13c50 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
13c60 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
13c70 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
13c80 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
13c90 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
13ca0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
13cb0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
13cc0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
13cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13ce0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
13cf0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
13d00 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
13d10 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
13d20 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
13d30 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
13d40 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
13d50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
13d60 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
13d70 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
13d80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13d90 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
13da0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
13db0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
13dc0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
13dd0 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
13de0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
13df0 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20  nteger argument 
13e00 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
13e10 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f  eted as.** a boo
13e20 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
13e30 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13e40 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
13e50 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
13e60 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65  or.** full table
13e70 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
13e80 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20  ery optimizer.  
13e90 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
13ea0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
13eb0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
13ec0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
13ed0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
13ee0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13ef0 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
13f00 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
13f10 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
13f20 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
13f30 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
13f40 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
13f50 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
13f60 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
13f70 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
13f80 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
13f90 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
13fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
13fb0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
13fc0 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77  ** malfunction w
13fd0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
13fe0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
13ff0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14000 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
14010 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
14020 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
14030 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
14040 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
14050 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
14060 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14070 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14080 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14090 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
140a0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
140b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
140c0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
140d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
140e0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
140f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14100 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
14110 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
14120 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
14130 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
14140 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
14150 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
14160 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14170 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14180 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14190 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
141a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
141b0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
141c0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
141d0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
141e0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
141f0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14200 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14210 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14220 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
14230 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
14240 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
14250 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
14260 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14270 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14280 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14290 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
142a0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
142b0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
142c0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
142d0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
142e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
142f0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14300 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14310 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14320 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14330 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14340 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14350 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14360 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14370 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14380 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
143a0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
143b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
143c0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
143d0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
143e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
143f0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
14400 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
14410 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
14420 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
14430 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
14440 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
14450 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
14460 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
14470 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
14480 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
14490 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
144a0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
144b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
144c0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
144d0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
144e0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
144f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14500 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
14510 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
14520 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
14530 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
14540 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
14550 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
14560 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
14570 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
14580 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
14590 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
145a0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
145b0 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
145c0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
145d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
145f0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
14600 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14610 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51  P_SIZE.** <dd>SQ
14620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14630 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
14640 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
14650 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
14660 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
14670 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
14680 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
14690 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
146a0 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
146b0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
146c0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
146d0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
146e0 6c 69 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65  limit..** The de
146f0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
14700 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
14710 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
14720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
14730 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
14740 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
14750 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
14760 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
14770 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
14780 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
14790 74 72 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d  trol.  The maxim
147a0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
147b0 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  size.** cannot b
147c0 65 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e  e changed at run
147d0 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20  -time.  Nor may 
147e0 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
147f0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
14800 20 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70   exceed the comp
14810 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
14820 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
14830 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
14840 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
14850 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14860 69 6f 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74  ion.  .** If eit
14870 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
14880 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
14890 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
148a0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
148b0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
148c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
148d0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  fault..** </dl>.
148e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
148f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
14900 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
14910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14920 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
14930 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
14940 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14950 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
14960 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
14970 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
14980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14990 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
149a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
149b0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
149c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
149d0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
149e0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
149f0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
14a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14a10 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
14a20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14a30 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14a40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14a50 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
14a60 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
14a70 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
14a80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14a90 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
14aa0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
14ab0 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
14ac0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
14ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14ae0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
14af0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
14b00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14b10 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
14b20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
14b30 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
14b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14b50 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
14b60 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
14b70 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
14b80 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
14b90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
14ba0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
14bb0 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
14bc0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
14bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14be0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
14bf0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
14c00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c10 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
14c20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
14c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14c40 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
14c50 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
14c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14c70 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
14c80 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
14c90 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
14ca0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14cb0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
14cc0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
14cd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14ce0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
14cf0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
14d00 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
14d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14d20 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d30 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
14d40 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14d50 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
14d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
14d70 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14d80 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
14d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14da0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
14db0 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
14dc0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
14dd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14de0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
14df0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
14e00 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
14e10 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4 */../*.** CAPI
14e20 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
14e30 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
14e40 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
14e50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
14e60 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
14e70 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
14e80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14e90 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
14ea0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
14eb0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14ec0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
14ed0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14ee0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
14ef0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
14f00 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
14f10 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
14f20 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
14f30 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
14f40 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
14f50 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
14f60 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
14f70 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
14f80 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
14f90 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
14fa0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
14fb0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
14fc0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
14fd0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
14fe0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
14ff0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15000 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
15010 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
15020 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
15030 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
15040 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
15050 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15060 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
15070 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
15080 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15090 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
150a0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
150b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
150c0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
150d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
150e0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
150f0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15100 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
15110 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
15120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15130 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
15140 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
15150 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
15160 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
15170 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
15180 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
15190 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
151a0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
151b0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
151c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
151d0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
151e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
151f0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
15200 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
15210 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
15220 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
15230 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
15240 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
15250 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
15260 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
15270 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
15280 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
15290 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
152a0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
152b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
152c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
152d0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
152e0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
152f0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
15300 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15310 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
15320 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
15330 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
15340 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
15350 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
15360 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
15370 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
15380 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
15390 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
153a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
153b0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
153c0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
153d0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
153e0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
153f0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
15400 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
15410 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
15420 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
15430 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
15440 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15450 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
15460 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
15470 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
15480 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
15490 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
154a0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
154b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
154c0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
154d0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
154e0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
154f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
15500 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
15510 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
15520 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
15530 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
15540 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
15550 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
15560 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
15570 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
15580 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
15590 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
155a0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
155b0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
155c0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
155d0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
155e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
155f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
15600 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
15610 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15620 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
15630 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
15640 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
15650 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
15660 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
15670 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
15680 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
15690 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
156a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
156b0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
156c0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
156d0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
156e0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
156f0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
15700 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
15710 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
15720 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
15730 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
15740 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15750 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
15760 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
15770 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
15780 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
15790 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
157a0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
157b0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
157c0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
157d0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
157e0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
157f0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
15800 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
15810 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
15820 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
15830 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
15840 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
15850 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
15860 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15870 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
15880 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
15890 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
158a0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
158b0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
158c0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
158d0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
158e0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
158f0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
15900 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
15910 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
15920 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
15930 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
15940 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
15950 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
15960 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
15970 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
15980 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
15990 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
159a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
159b0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
159c0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
159d0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
159e0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
159f0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
15a00 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
15a10 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15a20 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15a30 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15a40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15a50 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15a60 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
15a70 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
15a80 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
15a90 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
15aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15ab0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15ac0 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
15ad0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
15ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15af0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15b00 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
15b10 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
15b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15b30 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
15b40 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
15b50 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
15b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
15b70 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
15b80 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
15b90 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
15ba0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
15bb0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
15bc0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
15bd0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
15be0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15bf0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
15c00 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
15c10 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
15c20 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
15c30 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15c40 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
15c50 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
15c60 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
15c70 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
15c80 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
15c90 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
15ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
15cb0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
15cc0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
15cd0 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
15ce0 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
15cf0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
15d00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
15d10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
15d20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
15d30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
15d40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
15d50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
15d60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
15d70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
15d80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
15d90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
15da0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
15db0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
15dc0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
15dd0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
15de0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
15df0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
15e00 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
15e10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
15e20 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
15e30 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
15e40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
15e50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
15e60 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
15e70 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
15e80 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
15e90 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
15ea0 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
15eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15ec0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
15ed0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
15ee0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
15ef0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
15f00 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
15f10 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
15f20 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
15f30 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
15f40 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
15f50 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
15f60 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
15f70 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
15f80 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
15f90 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
15fa0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
15fb0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
15fc0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
15fd0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
15fe0 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
15ff0 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
16000 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
16010 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
16020 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
16030 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
16040 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
16050 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
16060 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
16070 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
16080 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
16090 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
160a0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
160b0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
160c0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
160d0 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
160e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
160f0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
16100 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
16110 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
16120 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
16130 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
16140 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
16150 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
16160 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
16170 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
16180 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
16190 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
161a0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
161b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
161c0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
161d0 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
161e0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
161f0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
16200 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
16210 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
16220 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
16230 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
16240 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
16250 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
16260 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
16270 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
16280 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16290 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
162a0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
162b0 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
162c0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
162d0 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
162e0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
162f0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
16300 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
16310 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
16320 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
16330 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
16340 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
16350 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
16360 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
16370 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
16380 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
16390 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
163a0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
163b0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
163c0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
163d0 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
163e0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
163f0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
16400 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
16410 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
16420 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
16430 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
16440 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
16450 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
16460 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
16470 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
16480 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
16490 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
164a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
164b0 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
164c0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
164d0 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
164e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
164f0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
16500 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
16510 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
16520 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
16530 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
16540 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16550 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
16560 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
16570 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
16580 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
16590 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
165a0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
165b0 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
165c0 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
165d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
165e0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
165f0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
16600 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
16610 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
16620 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
16630 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16640 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
16650 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
16660 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
16670 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
16680 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
16690 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
166a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
166b0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
166c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
166d0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
166e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
166f0 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
16700 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
16710 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
16720 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
16730 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
16740 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
16750 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
16760 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
16770 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
16780 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
16790 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
167a0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
167b0 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
167c0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
167d0 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
167e0 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
167f0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
16800 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
16810 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
16820 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
16830 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
16840 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
16850 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
16860 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
16870 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
16880 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
16890 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
168a0 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
168b0 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
168c0 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
168d0 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
168e0 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
168f0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
16900 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
16910 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
16920 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
16930 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
16940 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
16950 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
16960 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
16970 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
16980 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
16990 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
169a0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
169b0 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
169c0 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
169d0 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
169e0 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
169f0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
16a00 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
16a10 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
16a20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
16a30 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
16a40 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
16a50 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
16a60 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16a70 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
16a80 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
16a90 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
16aa0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
16ab0 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
16ac0 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
16ad0 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
16ae0 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
16af0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
16b00 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
16b10 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
16b20 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
16b30 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
16b40 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
16b50 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
16b60 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
16b70 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
16b80 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
16b90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
16ba0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
16bb0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
16bc0 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
16bd0 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
16be0 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
16bf0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
16c00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
16c10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
16c20 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
16c30 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
16c40 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
16c50 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
16c60 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
16c70 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
16c80 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
16c90 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
16ca0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
16cb0 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
16cc0 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
16cd0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
16ce0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
16cf0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
16d00 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
16d10 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
16d20 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
16d30 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
16d40 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
16d50 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
16d60 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
16d70 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
16d80 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
16d90 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
16da0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
16db0 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
16dc0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
16dd0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
16de0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
16df0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
16e00 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
16e10 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
16e20 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
16e30 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
16e40 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
16e50 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
16e60 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
16e70 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
16e80 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
16e90 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
16ea0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
16eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
16ec0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
16ed0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
16ee0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
16ef0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
16f00 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
16f10 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
16f20 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
16f30 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
16f40 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
16f50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16f60 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
16f70 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
16f80 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
16f90 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16fa0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
16fb0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
16fc0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
16fd0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
16fe0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16ff0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
17000 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
17010 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
17020 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17030 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17040 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
17050 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
17060 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
17070 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
17080 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
17090 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
170a0 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
170b0 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
170c0 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
170d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
170e0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
170f0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
17100 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
17110 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17120 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
17130 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
17140 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
17150 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
17160 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
17170 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17180 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
17190 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
171a0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
171b0 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
171c0 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
171d0 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
171e0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
171f0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
17200 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
17210 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
17220 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
17230 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17240 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
17250 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
17260 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
17270 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
17280 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
17290 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
172a0 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
172b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
172c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
172d0 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
172e0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
172f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
17300 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
17310 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
17320 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
17330 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
17340 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
17350 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
17360 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
17370 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
17380 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
17390 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
173a0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
173b0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
173c0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
173d0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
173e0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
173f0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17400 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
17410 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
17420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17430 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
17440 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17450 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
17460 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
17470 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
17480 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
17490 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
174a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
174b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
174c0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
174d0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
174e0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
174f0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
17500 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
17510 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
17520 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
17530 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
17540 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
17550 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
17560 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
17570 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
17580 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
17590 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
175a0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
175b0 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
175c0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
175d0 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
175e0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
175f0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
17600 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
17610 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
17620 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
17630 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
17640 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
17650 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
17660 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
17670 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
17680 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
17690 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
176a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
176b0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
176c0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
176d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
176e0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
176f0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
17700 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
17710 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
17720 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
17730 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
17740 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
17750 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
17760 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
17770 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
17780 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
17790 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
177a0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
177b0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
177c0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
177d0 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
177e0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
177f0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
17800 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
17810 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
17820 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
17830 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
17840 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
17850 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
17860 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
17870 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
17880 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
17890 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
178a0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
178b0 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
178c0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
178d0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
178e0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
178f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17900 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
17910 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
17920 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
17930 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
17940 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
17950 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
17960 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
17970 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
17980 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17990 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
179a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
179b0 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
179c0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
179d0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
179e0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
179f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
17a00 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
17a10 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
17a20 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
17a30 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
17a40 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
17a50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
17a60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
17a70 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
17a80 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
17a90 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
17aa0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
17ab0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
17ac0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
17ad0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
17ae0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
17af0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
17b00 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
17b10 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
17b20 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
17b30 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
17b40 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
17b50 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17b60 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17b70 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17b80 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
17b90 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
17ba0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17bb0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
17bc0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
17bd0 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
17be0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
17bf0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
17c00 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
17c10 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
17c20 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
17c30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17c40 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
17c50 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
17c60 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
17c70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17c80 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
17c90 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
17ca0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
17cb0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
17cc0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
17cd0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
17ce0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
17cf0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
17d00 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
17d10 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
17d20 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
17d30 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
17d40 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
17d50 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
17d60 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
17d70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
17d80 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
17d90 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
17da0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
17db0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
17dc0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
17dd0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
17de0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
17df0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
17e00 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
17e10 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
17e20 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
17e30 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
17e40 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
17e50 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
17e60 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
17e70 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
17e80 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
17e90 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
17ea0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
17eb0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
17ec0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
17ed0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
17ee0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
17ef0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
17f00 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
17f10 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
17f20 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
17f30 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
17f40 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
17f50 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
17f60 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
17f70 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
17f80 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
17f90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
17fa0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
17fb0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
17fc0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
17fd0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
17fe0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
17ff0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
18000 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
18010 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18020 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
18030 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
18040 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
18050 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
18060 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
18070 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
18080 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
18090 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
180a0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
180b0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
180c0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
180d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
180e0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
180f0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
18100 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
18110 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
18120 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
18130 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
18140 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
18150 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
18160 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
18170 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
18180 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
18190 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
181a0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
181b0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
181c0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
181d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
181e0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
181f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18200 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
18210 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
18220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
18230 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
18240 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
18250 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
18260 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
18270 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
18280 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18290 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
182a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
182b0 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
182c0 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
182d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
182e0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
182f0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
18300 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
18310 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
18320 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
18330 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
18340 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
18350 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
18360 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
18370 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
18380 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
18390 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
183a0 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
183b0 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
183c0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
183d0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
183e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
183f0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
18400 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
18410 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
18420 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
18430 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
18440 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
18450 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
18460 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
18470 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
18480 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
18490 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
184a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
184b0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
184c0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
184d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
184e0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
184f0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
18500 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
18510 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
18520 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
18530 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
18540 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18550 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
18560 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
18570 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
18580 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
18590 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
185a0 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
185b0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
185c0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
185d0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
185e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
185f0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
18600 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
18610 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
18620 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
18630 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18640 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
18650 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
18660 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
18670 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
18680 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
18690 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
186a0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
186b0 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
186c0 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
186d0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
186e0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
186f0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
18700 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
18710 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
18720 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
18730 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
18740 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
18750 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
18760 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
18770 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
18780 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
18790 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
187a0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
187b0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
187c0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
187d0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
187e0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
187f0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18800 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
18810 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
18820 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
18830 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
18840 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
18850 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
18860 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
18870 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
18880 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
18890 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
188a0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
188b0 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
188c0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
188d0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
188e0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
188f0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
18900 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
18910 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
18920 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
18930 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
18940 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
18950 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
18960 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
18970 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
18980 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
18990 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
189a0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
189b0 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
189c0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
189d0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
189e0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
189f0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
18a00 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
18a10 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
18a20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
18a30 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
18a40 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
18a50 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
18a60 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
18a70 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
18a80 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18a90 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18aa0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
18ab0 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
18ac0 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
18ad0 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
18ae0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
18af0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
18b00 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
18b10 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
18b20 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
18b30 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
18b40 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
18b50 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
18b60 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
18b70 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
18b80 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
18b90 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
18ba0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
18bb0 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
18bc0 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
18bd0 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
18be0 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
18bf0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
18c00 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
18c10 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
18c20 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
18c30 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
18c40 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
18c50 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
18c60 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
18c70 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
18c80 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
18c90 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
18ca0 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
18cb0 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
18cc0 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
18cd0 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
18ce0 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
18cf0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
18d00 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
18d10 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
18d20 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
18d30 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
18d40 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
18d50 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
18d60 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
18d70 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
18d80 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
18d90 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
18da0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
18db0 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
18dc0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
18dd0 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
18de0 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
18df0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
18e00 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
18e10 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
18e20 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
18e30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
18e40 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
18e50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18e60 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
18e70 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
18e80 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
18e90 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
18ea0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
18eb0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
18ec0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
18ed0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
18ee0 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
18ef0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
18f00 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
18f10 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
18f20 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
18f30 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
18f40 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
18f50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18f60 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18f70 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
18f80 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
18f90 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
18fa0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
18fb0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
18fc0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
18fd0 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
18fe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18ff0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
19000 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
19010 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19020 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
19030 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19040 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
19050 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
19060 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19070 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
19080 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
19090 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
190a0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
190b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
190c0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
190d0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
190e0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
190f0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
19100 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
19110 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
19120 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
19130 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
19140 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
19150 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19160 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
19170 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
19180 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
19190 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
191a0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
191b0 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
191c0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
191d0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
191e0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
191f0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
19200 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
19210 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
19220 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
19230 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
19240 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
19250 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
19260 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
19270 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
19280 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
19290 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
192a0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
192b0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
192c0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
192d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
192e0 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
192f0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
19300 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
19310 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
19320 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
19330 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
19340 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
19350 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
19360 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
19370 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
19380 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
19390 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
193a0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
193b0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
193c0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
193d0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
193e0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
193f0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
19400 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
19410 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
19420 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
19430 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
19440 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
19450 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
19460 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
19470 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
19480 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
19490 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
194a0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
194b0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
194c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
194d0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
194e0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
194f0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
19500 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
19510 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
19520 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
19530 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
19540 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
19550 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
19560 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
19570 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
19580 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
19590 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
195a0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
195b0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
195c0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
195d0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
195e0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
195f0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
19600 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
19610 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
19620 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
19630 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
19640 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
19650 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
19660 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
19670 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
19680 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
19690 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
196a0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
196b0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
196c0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
196d0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
196e0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
196f0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
19700 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
19710 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
19720 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
19730 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
19740 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
19750 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
19760 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
19770 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
19780 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19790 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
197a0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
197b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
197c0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
197d0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
197e0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
197f0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
19800 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19810 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
19820 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
19830 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
19840 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
19850 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
19860 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
19870 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
19880 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
19890 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
198a0 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
198b0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
198c0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
198d0 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
198e0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
198f0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
19900 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19910 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
19920 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
19930 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
19940 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19950 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
19960 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
19970 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
19980 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
19990 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
199a0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
199b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
199c0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
199d0 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
199e0 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
199f0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
19a00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
19a10 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
19a20 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
19a30 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
19a40 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
19a50 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
19a60 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
19a70 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
19a80 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19a90 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19aa0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19ab0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
19ac0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19ad0 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
19ae0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19af0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
19b00 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
19b10 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
19b20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
19b30 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
19b40 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
19b50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19b60 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
19b70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19b80 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
19b90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19ba0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
19bb0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
19bc0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
19bd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19be0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
19bf0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
19c00 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
19c10 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
19c20 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
19c30 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
19c40 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
19c50 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
19c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
19c70 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
19c80 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
19c90 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
19ca0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
19cb0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
19cc0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
19cd0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
19ce0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
19cf0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
19d00 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
19d10 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
19d20 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
19d30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
19d40 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
19d50 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
19d60 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
19d70 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
19d80 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
19d90 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
19da0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
19db0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
19dc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
19dd0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
19de0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
19df0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
19e00 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
19e10 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
19e20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
19e30 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
19e40 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
19e50 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
19e60 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
19e70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
19e80 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
19e90 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
19ea0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
19eb0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
19ec0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
19ed0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19ee0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
19ef0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
19f00 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
19f10 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
19f20 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
19f30 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
19f40 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
19f50 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
19f60 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
19f70 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
19f80 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
19f90 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
19fa0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
19fb0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
19fc0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
19fd0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
19fe0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
19ff0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1a000 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1a010 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1a020 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
1a030 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a040 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1a050 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1a060 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1a070 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a080 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1a090 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1a0a0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1a0b0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1a0c0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1a0d0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1a0e0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1a0f0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1a100 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1a110 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1a120 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1a130 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1a140 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1a150 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1a160 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1a170 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1a180 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1a190 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
1a1a0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1a1b0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1a1c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1a1d0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1a1e0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1a1f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1a200 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1a210 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1a220 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1a230 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1a240 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1a250 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
1a260 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1a270 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1a280 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1a290 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1a2a0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1a2b0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1a2c0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1a2d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1a2e0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1a2f0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1a300 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1a310 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1a320 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1a330 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1a340 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1a350 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1a360 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1a370 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1a380 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1a390 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1a3a0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1a3b0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1a3c0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1a3d0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1a3e0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1a3f0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1a400 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1a410 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1a420 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1a430 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1a440 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1a450 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1a460 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1a470 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1a480 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1a490 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1a4a0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1a4b0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1a4c0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1a4d0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1a4e0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1a4f0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1a500 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1a510 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1a520 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1a530 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1a540 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1a550 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1a560 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1a570 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1a580 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1a590 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1a5a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1a5b0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1a5c0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1a5d0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1a5e0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1a5f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1a600 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1a610 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1a620 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1a630 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1a640 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1a650 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1a660 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1a670 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1a680 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1a690 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a6a0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1a6b0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1a6c0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1a6d0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1a6e0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1a6f0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1a700 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1a710 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1a720 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1a730 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1a740 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1a750 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1a760 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1a770 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1a780 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1a790 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1a7a0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1a7b0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1a7c0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1a7d0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1a7e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a7f0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1a800 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1a810 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1a820 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1a840 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1a850 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1a860 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1a870 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1a880 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1a890 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1a8a0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1a8b0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1a8c0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1a8d0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1a8e0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1a8f0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1a900 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
1a910 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1a920 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1a930 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1a940 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1a950 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1a960 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1a970 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1a980 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1a990 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1a9a0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1a9b0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1a9c0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1a9d0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1a9e0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1a9f0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1aa00 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1aa10 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1aa20 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1aa30 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1aa40 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1aa50 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1aa60 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1aa70 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1aa80 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1aa90 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1aaa0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1aab0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1aac0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1aad0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1aae0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1aaf0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ab00 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1ab10 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1ab20 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1ab30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1ab40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ab50 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1ab60 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1ab70 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1ab80 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1ab90 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1aba0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1abb0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1abc0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1abd0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1abe0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1abf0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1ac00 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1ac10 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1ac20 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1ac30 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1ac40 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1ac50 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1ac60 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1ac70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ac80 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1ac90 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1aca0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1acb0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1acc0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1acd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1ace0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1acf0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1ad00 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1ad10 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1ad20 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1ad30 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1ad40 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ad50 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1ad60 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1ad70 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1ad80 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1ad90 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1ada0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1adb0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1adc0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1add0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1ade0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1adf0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1ae00 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1ae10 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1ae20 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1ae30 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1ae40 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1ae50 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1ae60 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1ae70 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1ae80 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1ae90 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1aea0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1aeb0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1aec0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1aed0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1aee0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1aef0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1af00 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1af10 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1af20 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1af30 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1af40 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1af50 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1af60 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1af70 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1af80 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1af90 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1afa0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1afb0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1afc0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1afd0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1afe0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1aff0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b000 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1b010 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1b020 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1b030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1b040 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1b050 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1b060 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1b070 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b080 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1b090 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1b0a0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b0b0 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1b0c0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1b0d0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1b0e0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1b0f0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1b100 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1b110 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1b120 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1b130 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1b140 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1b150 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1b160 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1b170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1b180 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1b190 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1b1a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1b1b0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1b1c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1b1d0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1b1e0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1b1f0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1b200 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1b210 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1b220 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1b230 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1b240 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1b250 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1b260 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1b270 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1b280 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1b290 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1b2a0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1b2b0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1b2c0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1b2d0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1b2e0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1b2f0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1b300 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1b310 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1b320 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1b330 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1b340 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1b350 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1b360 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1b370 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1b380 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1b390 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1b3a0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1b3b0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1b3c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1b3d0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1b3e0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1b3f0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1b400 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1b410 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1b420 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1b430 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1b440 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1b450 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1b460 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1b470 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1b480 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1b490 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1b4a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1b4b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1b4c0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1b4d0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1b4e0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1b4f0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1b500 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1b510 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1b520 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1b530 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1b540 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1b550 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1b560 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1b570 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1b580 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1b590 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1b5a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1b5b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1b5c0 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1b5d0 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1b5e0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1b5f0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1b600 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1b610 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1b620 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1b630 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1b640 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1b650 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1b660 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1b670 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1b680 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1b690 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1b6a0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1b6b0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1b6c0 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1b6d0 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1b6e0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1b6f0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1b700 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1b710 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1b720 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1b730 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1b740 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1b750 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
1b760 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1b770 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1b780 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1b790 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
1b7a0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
1b7b0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
1b7c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1b7d0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
1b7e0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
1b7f0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
1b800 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
1b810 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
1b820 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1b830 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1b840 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1b850 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1b860 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1b870 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1b880 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1b890 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
1b8a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b8b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1b8c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
1b8d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1b8e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1b8f0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
1b900 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1b910 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1b920 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1b930 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1b940 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1b950 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
1b960 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b970 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b980 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
1b990 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b9a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b9b0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1b9c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1b9d0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1b9e0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1b9f0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
1ba00 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
1ba10 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1ba20 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1ba30 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ba40 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1ba50 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1ba60 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ba70 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1ba80 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1ba90 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1baa0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1bab0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
1bac0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1bad0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1bae0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1baf0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1bb00 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
1bb10 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
1bb20 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
1bb30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1bb40 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1bb50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1bb60 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1bb70 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
1bb80 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1bb90 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1bba0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1bbb0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1bbc0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1bbd0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1bbe0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1bbf0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1bc00 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1bc10 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1bc20 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1bc30 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1bc40 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1bc50 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1bc60 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1bc70 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1bc80 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1bc90 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1bca0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1bcb0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1bcc0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1bcd0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1bce0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1bcf0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1bd00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1bd10 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1bd20 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1bd30 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1bd40 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1bd50 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1bd60 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1bd70 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1bd80 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1bd90 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1bda0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1bdb0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1bdc0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1bdd0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1bde0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1bdf0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1be00 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1be10 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1be20 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1be30 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1be40 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1be50 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1be60 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1be70 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1be80 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1be90 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1bea0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1beb0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1bec0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1bed0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1bee0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1bef0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1bf00 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1bf10 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1bf20 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1bf30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1bf40 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1bf50 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1bf60 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1bf70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1bf80 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1bf90 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1bfa0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1bfb0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1bfc0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1bfd0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1bfe0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1bff0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1c000 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1c010 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1c020 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1c030 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1c040 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1c050 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1c060 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1c070 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1c080 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1c090 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1c0a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1c0b0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1c0c0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1c0d0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1c0e0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1c0f0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1c100 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1c110 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1c120 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1c130 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1c140 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1c150 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1c160 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1c170 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1c180 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1c190 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1c1a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1c1b0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1c1c0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1c1d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1c1e0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1c1f0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1c200 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1c210 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1c220 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1c230 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c240 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1c250 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1c260 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1c270 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c280 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1c290 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1c2a0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1c2b0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1c2c0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1c2d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c2e0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1c2f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c300 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1c310 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1c320 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1c330 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1c340 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1c350 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1c360 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1c370 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1c380 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1c390 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1c3a0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1c3b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1c3c0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1c3d0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1c3e0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1c3f0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1c400 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1c410 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c420 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1c430 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1c440 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1c450 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c460 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1c470 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c480 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1c490 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1c4a0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1c4b0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1c4c0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1c4d0 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1c4e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1c4f0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1c500 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1c510 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1c520 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1c530 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1c540 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1c550 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1c560 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1c570 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1c580 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1c590 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1c5a0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1c5b0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1c5c0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1c5d0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1c5e0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1c5f0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1c600 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1c610 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1c620 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1c630 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1c640 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1c650 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1c660 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1c670 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1c680 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1c690 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1c6a0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1c6b0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1c6c0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1c6d0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1c6e0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1c6f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1c700 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1c710 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1c720 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1c730 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1c740 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1c750 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1c760 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1c770 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1c780 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1c790 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1c7a0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1c7b0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1c7c0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1c7d0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1c7e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c7f0 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1c800 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1c810 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1c820 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1c830 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1c840 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1c850 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1c860 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1c870 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1c880 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1c890 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1c8a0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1c8b0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1c8c0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1c8d0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1c8e0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1c8f0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1c900 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1c910 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c920 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1c930 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1c940 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1c950 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1c960 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1c970 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1c980 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1c990 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1c9a0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1c9b0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1c9c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1c9d0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1c9e0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1c9f0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1ca00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1ca10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ca20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1ca30 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1ca40 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1ca50 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1ca60 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1ca70 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1ca80 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1ca90 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1caa0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1cab0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1cac0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1cad0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1cae0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1caf0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1cb00 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1cb10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1cb20 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1cb30 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1cb40 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1cb50 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1cb60 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1cb70 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1cb80 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1cb90 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1cba0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1cbb0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1cbc0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1cbd0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1cbe0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1cbf0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1cc00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1cc10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1cc20 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1cc30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1cc40 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1cc50 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1cc60 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1cc70 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1cc80 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1cc90 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1cca0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1ccb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1ccc0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1ccd0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1cce0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1ccf0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1cd00 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1cd10 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1cd20 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1cd30 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1cd40 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1cd50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1cd60 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1cd70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1cd80 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1cd90 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1cda0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1cdb0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1cdc0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1cdd0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1cde0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1cdf0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1ce00 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1ce10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1ce20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ce30 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1ce40 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1ce50 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1ce60 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1ce70 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1ce80 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1ce90 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1cea0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1ceb0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1cec0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1ced0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1cee0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1cef0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1cf00 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1cf10 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1cf20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1cf30 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1cf40 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1cf50 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1cf60 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1cf70 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1cf80 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1cf90 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1cfa0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1cfb0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1cfc0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1cfd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1cfe0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1cff0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1d000 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1d010 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1d020 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1d030 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1d040 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1d050 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1d060 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1d070 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1d080 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1d090 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1d0a0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1d0b0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1d0c0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1d0d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1d0e0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1d0f0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1d100 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1d110 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1d120 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1d130 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1d140 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1d150 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1d160 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1d170 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1d180 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1d190 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1d1a0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1d1b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1d1c0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1d1d0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1d1e0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1d1f0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1d200 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1d210 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1d220 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1d230 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1d240 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1d250 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1d260 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1d270 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1d280 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1d290 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1d2a0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1d2b0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1d2c0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1d2d0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1d2e0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1d2f0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1d300 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1d310 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1d320 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1d330 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1d340 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1d350 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1d360 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1d370 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1d380 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1d390 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1d3a0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1d3b0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1d3c0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1d3d0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1d3e0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1d3f0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1d400 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1d410 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1d420 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1d430 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1d440 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1d450 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1d460 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1d470 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1d480 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1d490 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1d4a0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1d4b0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1d4c0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1d4d0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1d4e0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1d4f0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1d500 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1d510 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1d520 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1d530 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1d540 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1d550 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1d560 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1d570 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1d580 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1d590 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1d5a0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1d5b0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1d5c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1d5d0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1d5e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1d5f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1d600 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1d610 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1d620 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1d630 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1d640 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1d650 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1d660 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1d670 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1d680 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1d690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d6a0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1d6b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1d6c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1d6d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d6e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1d6f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d700 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1d710 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1d720 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1d730 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d740 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1d750 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1d760 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1d770 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1d780 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1d790 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1d7a0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1d7b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1d7c0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1d7d0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1d7e0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1d7f0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1d800 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1d810 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1d820 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1d830 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1d840 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1d850 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1d860 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1d870 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1d880 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1d890 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1d8a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1d8b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1d8c0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1d8d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d8e0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1d8f0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1d900 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1d910 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1d920 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1d930 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1d940 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1d950 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1d960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1d970 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1d980 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1d990 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1d9a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1d9b0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1d9c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1d9d0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1d9e0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1d9f0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1da00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1da10 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1da20 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1da30 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1da40 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1da50 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1da60 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1da70 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1da80 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1da90 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1daa0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1dab0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1dac0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1dad0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1dae0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1daf0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1db00 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1db10 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1db20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1db30 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1db40 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1db50 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1db60 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1db70 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1db80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1db90 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1dba0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1dbb0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1dbc0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1dbd0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1dbe0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1dbf0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1dc00 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1dc10 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1dc20 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1dc30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1dc40 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1dc50 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1dc60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1dc70 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1dc80 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1dc90 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1dca0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1dcb0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1dcc0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1dcd0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1dce0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1dcf0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1dd00 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1dd10 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1dd20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1dd30 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1dd40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1dd50 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1dd60 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1dd70 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1dd80 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1dd90 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1dda0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1ddb0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1ddc0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1ddd0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1dde0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1ddf0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1de00 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1de10 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1de20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1de30 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1de40 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1de50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1de60 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1de70 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1de80 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1de90 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1dea0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1deb0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1dec0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1ded0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1dee0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1def0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1df00 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1df10 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1df20 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1df30 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1df40 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1df50 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1df60 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1df70 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1df80 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1df90 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1dfa0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1dfb0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1dfc0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1dfd0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1dfe0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1dff0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1e000 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e010 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1e020 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1e030 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1e040 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1e050 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1e060 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1e070 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1e080 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1e090 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1e0a0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1e0b0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1e0c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e0d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e0e0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1e0f0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1e100 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1e110 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e120 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1e130 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e140 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1e150 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e160 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e170 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1e180 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e190 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e1a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e1b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e1c0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1e1d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e1e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e1f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e200 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e210 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1e220 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e230 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e240 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e250 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e260 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1e270 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1e280 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e290 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e2a0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e2b0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1e2c0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1e2d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e2e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e2f0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1e300 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1e310 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e320 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e340 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1e350 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1e360 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e370 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e390 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1e3a0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1e3b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e3c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e3d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e3e0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1e3f0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1e400 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e410 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e430 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1e440 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1e450 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e460 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e480 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1e490 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1e4a0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e4b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e4c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e4d0 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1e4e0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1e4f0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e500 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e510 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e520 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1e530 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1e540 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e550 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e560 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e570 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1e580 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1e590 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1e5a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e5b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e5c0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1e5d0 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1e5e0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e5f0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e600 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1e610 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1e620 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e630 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e640 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e650 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1e660 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1e670 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e680 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e690 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e6a0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1e6b0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1e6c0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1e6d0 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1e6e0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1e6f0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1e700 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1e710 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e720 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1e730 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e740 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1e750 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1e760 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1e770 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e780 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e790 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1e7a0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1e7b0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1e7c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e7d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e7e0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1e7f0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1e800 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e810 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1e820 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e830 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1e840 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1e850 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1e860 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e880 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1e890 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1e8a0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1e8b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e8c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e8d0 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1e8e0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1e8f0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1e900 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1e920 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1e930 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1e940 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1e950 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1e970 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1e980 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1e990 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e9a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e9c0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1e9d0 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1e9e0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1e9f0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1ea00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ea10 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1ea20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1ea30 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1ea40 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1ea50 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1ea60 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1ea70 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1ea80 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1ea90 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1eaa0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1eab0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1eac0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1ead0 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1eae0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1eaf0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1eb00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1eb10 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1eb20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1eb30 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1eb40 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1eb50 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1eb60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1eb70 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1eb80 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1eb90 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1eba0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1ebb0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1ebc0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1ebd0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1ebe0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1ebf0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1ec00 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1ec10 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1ec20 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1ec30 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1ec40 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1ec50 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1ec60 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1ec70 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1ec80 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1ec90 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1eca0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1ecb0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1ecc0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1ecd0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1ece0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1ecf0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1ed00 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1ed10 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1ed20 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1ed30 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1ed40 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1ed50 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1ed60 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1ed70 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1ed80 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1ed90 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1eda0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1edb0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
1edc0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
1edd0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
1ede0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
1edf0 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
1ee00 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
1ee10 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
1ee20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
1ee30 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
1ee40 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
1ee50 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1ee60 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1ee70 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1ee80 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1ee90 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1eea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1eeb0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1eec0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1eed0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1eee0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1eef0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1ef00 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1ef10 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1ef20 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1ef30 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1ef40 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1ef50 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1ef60 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1ef70 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1ef80 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1ef90 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1efa0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1efb0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1efc0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1efd0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1efe0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1eff0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1f000 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1f010 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1f020 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1f030 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1f040 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1f050 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1f060 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1f070 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1f080 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1f090 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1f0a0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1f0b0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1f0c0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1f0d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1f0e0 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
1f0f0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1f100 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1f110 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1f120 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1f130 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1f140 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1f150 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1f160 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1f170 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1f180 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1f190 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1f1a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f1b0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1f1c0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1f1d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1f1e0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1f1f0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1f200 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1f210 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1f220 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1f230 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1f240 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1f250 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1f260 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1f270 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f280 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1f290 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1f2a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1f2b0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1f2c0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1f2d0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1f2e0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1f2f0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1f300 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1f310 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1f320 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1f330 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1f340 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1f350 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1f360 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1f370 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1f380 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
1f390 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
1f3a0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
1f3b0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
1f3c0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
1f3d0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
1f3e0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
1f3f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
1f400 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
1f410 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
1f420 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
1f430 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
1f440 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
1f450 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1f460 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f470 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1f480 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1f490 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f4a0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1f4b0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1f4c0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1f4d0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1f4e0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1f4f0 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1f500 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1f510 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1f520 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1f530 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1f540 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1f550 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1f560 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1f570 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1f580 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1f590 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1f5a0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1f5b0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1f5c0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1f5d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1f5e0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1f5f0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1f600 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1f610 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1f620 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1f630 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1f640 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1f650 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1f660 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1f670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f680 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1f690 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f6a0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1f6b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f6c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1f6d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1f6e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1f6f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f700 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1f710 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1f720 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1f730 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1f740 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1f750 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1f760 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1f770 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1f780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f790 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1f7a0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1f7b0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1f7c0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1f7d0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1f7e0 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
1f7f0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
1f800 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1f810 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
1f820 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
1f830 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
1f840 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1f850 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1f860 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
1f870 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1f880 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
1f890 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
1f8a0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
1f8b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f8c0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
1f8d0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
1f8e0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
1f8f0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
1f900 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
1f910 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
1f920 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
1f930 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1f940 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
1f950 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
1f960 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
1f970 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1f980 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1f990 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1f9a0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f9b0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1f9c0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
1f9d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1f9e0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1f9f0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1fa00 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1fa10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1fa20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1fa30 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1fa40 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
1fa50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1fa60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1fa70 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1fa80 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1fa90 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1faa0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1fab0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1fac0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
1fad0 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
1fae0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
1faf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
1fb00 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
1fb10 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1fb20 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1fb30 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1fb40 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1fb50 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1fb60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1fb70 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1fb80 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1fb90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1fba0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1fbb0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1fbc0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1fbd0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1fbe0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1fbf0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1fc00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1fc10 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1fc20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1fc30 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1fc40 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1fc50 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1fc60 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1fc70 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1fc80 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1fc90 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1fca0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1fcb0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1fcc0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1fcd0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1fce0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1fcf0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1fd00 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1fd10 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1fd20 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1fd30 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
1fd40 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1fd50 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
1fd60 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
1fd70 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1fd80 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1fd90 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1fda0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1fdb0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1fdc0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1fdd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1fde0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
1fdf0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1fe00 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
1fe10 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1fe20 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
1fe30 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1fe40 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
1fe50 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1fe60 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1fe70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1fe80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1fe90 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1fea0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1feb0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1fec0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1fed0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1fee0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1fef0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1ff00 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1ff10 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1ff20 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1ff30 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1ff40 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1ff50 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1ff60 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1ff70 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1ff80 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1ff90 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1ffa0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1ffb0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1ffc0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1ffd0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1ffe0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1fff0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
20000 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
20010 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
20020 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
20030 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
20040 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
20050 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
20060 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
20070 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
20080 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
20090 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
200a0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
200b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
200c0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
200d0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
200e0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
200f0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
20100 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
20110 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
20120 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20130 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
20140 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
20150 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
20160 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
20170 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
20180 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
20190 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
201a0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
201b0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
201c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
201d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
201e0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
201f0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
20200 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
20210 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
20220 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
20230 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
20240 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
20250 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
20260 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
20270 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
20280 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
20290 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
202a0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
202b0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
202c0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
202d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
202e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
202f0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
20300 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
20310 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
20320 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
20330 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
20340 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
20350 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
20360 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
20370 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
20380 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20390 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
203a0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
203b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
203c0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
203d0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
203e0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
203f0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
20400 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
20410 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
20420 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20430 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
20440 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
20450 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
20460 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
20470 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
20480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20490 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
204a0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
204b0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
204c0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
204d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
204e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
204f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20500 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
20510 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
20520 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
20530 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
20540 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20550 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
20560 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
20570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20580 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
20590 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
205a0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
205b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
205c0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
205d0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
205e0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
205f0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
20600 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
20610 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
20620 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
20630 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
20640 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
20650 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
20660 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
20670 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
20680 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
20690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
206a0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
206b0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
206c0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
206d0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
206e0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
206f0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
20700 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
20710 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
20720 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
20730 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
20740 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
20750 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
20760 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
20770 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
20780 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
20790 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
207a0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
207b0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
207c0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
207d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
207e0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
207f0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
20800 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
20810 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
20820 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
20830 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
20840 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
20850 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
20860 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
20870 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
20880 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20890 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
208a0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
208b0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
208c0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
208d0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
208e0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
208f0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
20900 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
20910 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
20920 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20930 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
20940 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
20950 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
20960 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
20970 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
20980 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
20990 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
209a0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
209b0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
209c0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
209d0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
209e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
209f0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
20a00 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
20a10 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
20a20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
20a30 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
20a40 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
20a50 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
20a60 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
20a70 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
20a80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
20a90 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
20aa0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
20ab0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
20ac0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
20ad0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
20ae0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
20af0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
20b00 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20b10 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
20b20 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
20b30 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
20b40 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
20b50 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
20b60 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
20b70 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
20b80 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
20b90 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
20ba0 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
20bb0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
20bc0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
20bd0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
20be0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
20bf0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
20c00 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
20c10 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
20c20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
20c30 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
20c40 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
20c50 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
20c60 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
20c70 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
20c80 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
20c90 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
20ca0 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
20cb0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
20cc0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
20cd0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
20ce0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
20cf0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
20d00 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
20d10 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
20d20 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
20d30 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
20d40 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
20d50 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
20d60 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20d70 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
20d80 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
20d90 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
20da0 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
20db0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
20dc0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
20dd0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
20de0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
20df0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
20e00 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
20e10 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
20e20 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
20e30 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
20e40 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
20e50 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
20e60 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
20e70 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
20e80 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
20e90 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
20ea0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
20eb0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
20ec0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
20ed0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
20ee0 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
20ef0 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
20f00 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
20f10 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
20f20 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
20f30 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
20f40 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
20f50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
20f60 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
20f70 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
20f80 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
20f90 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
20fa0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
20fb0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
20fc0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
20fd0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
20fe0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
20ff0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
21000 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
21010 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
21020 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
21030 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
21040 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
21050 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
21060 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
21070 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
21080 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
21090 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
210a0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
210b0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
210c0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
210d0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
210e0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
210f0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
21100 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
21110 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
21120 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
21130 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
21140 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
21150 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
21160 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
21170 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21180 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21190 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
211a0 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
211b0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
211c0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
211d0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
211e0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
211f0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
21200 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
21210 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
21220 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
21230 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
21240 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
21250 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
21260 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21270 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
21280 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
21290 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
212a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
212b0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
212c0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
212d0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
212e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
212f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21300 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
21310 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
21320 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
21330 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21340 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21350 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
21360 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
21370 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
21380 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21390 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
213a0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
213b0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
213c0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
213d0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
213e0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
213f0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
21400 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21410 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
21420 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
21430 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
21440 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
21450 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
21460 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
21470 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
21480 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
21490 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
214a0 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
214b0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
214c0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
214d0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
214e0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
214f0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
21500 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
21510 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
21520 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
21530 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
21540 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
21550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21560 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
21570 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
21580 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
21590 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
215a0 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
215b0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
215c0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
215d0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
215e0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
215f0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
21600 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
21610 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
21620 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
21630 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
21640 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
21650 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
21660 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
21670 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
21680 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
21690 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
216a0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
216b0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
216c0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
216d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
216e0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
216f0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
21700 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
21710 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
21720 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
21730 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
21740 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
21750 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
21760 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
21770 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
21780 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
21790 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
217a0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
217b0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
217c0 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
217d0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
217e0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
217f0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
21800 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
21810 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21820 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
21830 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
21840 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
21850 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
21860 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
21870 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
21880 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
21890 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
218a0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
218b0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
218c0 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
218d0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
218e0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
218f0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
21900 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
21910 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
21920 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
21930 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
21940 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
21950 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
21960 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
21970 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
21980 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
21990 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
219a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
219b0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
219c0 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
219d0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
219e0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
219f0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
21a00 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
21a10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21a20 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
21a30 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
21a40 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
21a50 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
21a60 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
21a70 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
21a80 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
21a90 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
21aa0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
21ab0 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
21ac0 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
21ad0 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
21ae0 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
21af0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
21b00 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
21b10 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
21b20 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
21b30 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
21b40 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
21b50 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
21b60 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
21b70 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
21b80 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
21b90 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
21ba0 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
21bb0 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
21bc0 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
21bd0 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
21be0 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
21bf0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
21c00 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
21c10 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
21c20 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
21c30 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
21c40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21c50 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
21c60 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
21c70 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21c80 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
21c90 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
21ca0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
21cb0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
21cc0 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
21cd0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
21ce0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
21cf0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
21d00 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
21d10 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
21d20 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
21d30 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
21d40 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
21d50 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
21d60 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a  nix-nolock <td>.
21d70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21d80 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
21d90 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
21da0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
21db0 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a  "unix-nolock"..*
21dc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21dd0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
21de0 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
21df0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
21e00 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
21e10 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
21e20 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
21e30 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
21e40 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
21e50 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
21e60 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
21e70 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
21e80 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
21e90 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
21ea0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
21eb0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
21ec0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
21ed0 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
21ee0 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
21ef0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
21f00 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
21f10 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
21f20 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
21f30 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
21f40 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
21f50 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
21f60 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
21f70 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
21f80 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
21f90 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
21fa0 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
21fb0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
21fc0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
21fd0 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
21fe0 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
21ff0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
22000 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
22010 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
22020 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
22030 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
22040 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
22050 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
22060 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
22070 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
22080 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
22090 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
220a0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
220b0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
220c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
220d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
220e0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
220f0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
22100 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
22110 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
22120 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
22130 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
22140 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
22150 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
22160 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
22170 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
22180 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
22190 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
221a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
221b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
221c0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
221d0 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
221e0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
221f0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
22200 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
22210 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
22220 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
22230 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
22240 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
22250 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
22260 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
22270 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
22280 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
22290 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
222a0 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
222b0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
222c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
222d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
222e0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
222f0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22300 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
22310 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22320 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22330 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
22340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
22350 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
22360 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
22370 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
22380 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
22390 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
223a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
223b0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
223c0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
223d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
223e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
223f0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
22400 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22410 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
22420 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
22430 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22440 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
22450 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
22460 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
22470 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22480 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
22490 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
224a0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
224b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
224c0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
224d0 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
224e0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
224f0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
22500 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
22510 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
22520 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
22530 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
22540 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
22550 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
22560 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
22570 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
22580 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
22590 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
225a0 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
225b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
225c0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
225d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
225e0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
225f0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
22600 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
22610 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
22620 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
22630 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
22640 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
22650 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
22660 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
22670 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
22680 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
22690 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
226a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
226b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
226c0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
226d0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
226e0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
226f0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
22700 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
22710 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
22720 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
22730 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
22740 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
22750 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
22760 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
22770 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
22780 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
22790 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
227a0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
227b0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
227c0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
227d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
227e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
227f0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22800 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
22810 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
22820 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
22830 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
22840 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
22850 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
22860 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
22870 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
22880 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22890 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
228a0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
228b0 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
228c0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
228d0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
228e0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
228f0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
22900 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
22910 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
22920 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
22930 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
22940 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22950 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
22960 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
22970 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
22980 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
22990 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
229a0 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
229b0 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
229c0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
229d0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
229e0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
229f0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
22a00 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
22a10 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
22a20 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
22a30 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
22a40 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
22a50 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
22a60 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22a70 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
22a80 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
22a90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
22aa0 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
22ab0 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
22ac0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
22ad0 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
22ae0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
22af0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
22b00 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
22b10 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
22b20 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
22b30 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
22b40 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
22b50 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
22b60 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
22b70 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
22b80 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
22b90 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
22ba0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
22bb0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
22bc0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
22bd0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22be0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
22bf0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
22c00 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
22c10 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
22c20 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
22c30 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
22c40 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
22c50 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
22c60 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
22c70 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
22c80 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
22c90 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
22ca0 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
22cb0 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
22cc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
22cd0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
22ce0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
22cf0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
22d00 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
22d10 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22d20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
22d30 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
22d40 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
22d50 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
22d60 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
22d70 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
22d80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
22d90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
22da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22db0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
22dc0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
22dd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
22de0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
22df0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
22e00 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
22e10 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
22e20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
22e30 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
22e40 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
22e50 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
22e60 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
22e70 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
22e80 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
22e90 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
22ea0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
22eb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
22ec0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
22ed0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
22ee0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
22ef0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
22f00 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
22f10 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
22f20 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
22f30 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
22f40 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
22f50 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
22f60 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
22f70 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
22f80 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
22f90 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
22fa0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
22fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
22fc0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
22fd0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
22fe0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
22ff0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
23000 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
23010 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
23020 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
23030 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
23040 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
23050 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
23060 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
23070 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
23080 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
23090 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
230a0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
230b0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
230c0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
230d0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
230e0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
230f0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
23100 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
23110 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
23120 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
23130 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
23140 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
23150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23160 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
23170 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
23180 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
23190 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
231a0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
231b0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
231c0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
231d0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
231e0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
231f0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
23200 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
23210 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
23220 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
23230 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
23240 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
23250 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
23260 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
23270 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
23280 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
23290 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
232a0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
232b0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
232c0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
232d0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
232e0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
232f0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
23300 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
23310 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
23320 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
23330 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
23340 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
23350 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
23360 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23370 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
23380 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
23390 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
233a0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
233b0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
233c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
233d0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
233e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
233f0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
23400 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
23410 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
23420 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
23430 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
23440 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
23450 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
23460 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
23470 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
23480 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
23490 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
234a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
234b0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
234c0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
234d0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
234e0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
234f0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
23500 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
23510 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
23520 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
23530 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
23540 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
23550 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
23560 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
23570 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
23580 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
23590 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
235a0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
235b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
235c0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
235d0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
235e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
235f0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
23600 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23610 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
23620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23630 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
23640 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
23650 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
23660 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
23670 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
23680 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
23690 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
236a0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
236b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
236c0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
236d0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
236e0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
236f0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
23700 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
23710 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
23720 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
23730 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
23740 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
23750 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
23760 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
23770 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
23780 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
23790 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
237a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
237b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
237c0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
237d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
237e0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
237f0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
23800 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
23810 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
23820 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
23830 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
23840 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
23850 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23860 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
23870 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
23880 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
23890 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
238a0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
238b0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
238c0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
238d0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
238e0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
238f0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
23900 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23910 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
23920 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
23930 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
23940 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
23950 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
23960 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
23970 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23980 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
23990 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
239a0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
239b0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
239c0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
239d0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
239e0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
239f0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
23a00 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
23a10 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
23a20 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
23a30 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
23a40 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
23a50 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
23a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23a70 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
23a80 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
23a90 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
23aa0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23ab0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
23ac0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
23ad0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
23ae0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
23af0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
23b00 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
23b10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23b20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
23b30 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
23b40 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
23b50 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
23b60 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
23b70 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
23b80 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
23b90 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
23ba0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
23bb0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
23bc0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
23bd0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
23be0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
23bf0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
23c00 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
23c10 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
23c20 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
23c30 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
23c40 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
23c50 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
23c60 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
23c70 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
23c80 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
23c90 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
23ca0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
23cb0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
23cc0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
23cd0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
23ce0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
23cf0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
23d00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23d10 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
23d20 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
23d30 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
23d40 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
23d50 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23d60 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
23d70 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
23d80 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
23d90 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
23da0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
23db0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
23dc0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
23dd0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
23de0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
23df0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
23e00 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
23e10 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
23e20 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
23e30 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
23e40 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
23e50 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
23e60 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
23e70 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
23e80 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
23e90 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
23ea0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
23eb0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
23ec0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
23ed0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
23ee0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
23ef0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
23f00 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
23f10 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
23f20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
23f30 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
23f40 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
23f50 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
23f60 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
23f70 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
23f80 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
23f90 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
23fa0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
23fb0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
23fc0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
23fd0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
23fe0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
23ff0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
24000 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
24010 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
24020 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
24030 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
24040 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
24050 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
24060 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
24070 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
24080 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
24090 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
240a0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
240b0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
240c0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
240d0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
240e0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
240f0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
24100 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
24110 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
24120 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
24130 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
24140 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
24150 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
24160 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
24170 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
24180 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
24190 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
241a0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
241b0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
241c0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
241d0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
241e0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
241f0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
24200 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
24210 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
24220 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
24230 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
24240 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
24250 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24260 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
24270 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
24280 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
24290 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
242a0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
242b0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
242c0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
242d0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
242e0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
242f0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
24300 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
24310 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
24320 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24330 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
24340 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
24350 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
24360 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
24370 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
24380 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
24390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
243a0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
243b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
243c0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
243d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
243e0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
243f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
24400 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
24410 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24420 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
24430 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
24440 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
24450 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24460 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
24470 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
24480 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
24490 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
244a0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
244b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
244c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
244d0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
244e0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
244f0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
24500 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24510 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
24520 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
24530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
24540 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
24550 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24560 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
24570 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
24580 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
24590 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
245a0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
245b0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
245c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
245d0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
245e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
245f0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
24600 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
24610 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
24620 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
24630 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24640 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
24650 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
24660 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
24670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24680 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
24690 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
246a0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
246b0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
246c0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
246d0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
246e0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
246f0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
24700 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
24710 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
24720 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
24730 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
24740 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24750 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
24760 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
24770 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24780 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
24790 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
247a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
247b0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
247c0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
247d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
247e0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
247f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24800 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
24810 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24820 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
24830 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
24840 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
24850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
24860 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
24870 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
24880 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24890 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
248a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
248b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
248c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
248d0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
248e0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
248f0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
24900 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
24910 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24920 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
24930 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
24940 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
24950 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
24960 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24970 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
24980 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
24990 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
249a0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
249b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
249c0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
249d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
249e0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
249f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24a00 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24a10 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
24a20 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
24a30 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
24a40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
24a50 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
24a60 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
24a70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24a80 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
24a90 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
24aa0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24ab0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
24ac0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
24ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24ae0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
24af0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
24b00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24b10 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
24b20 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
24b30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24b40 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
24b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
24b60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24b70 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
24b80 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
24b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24ba0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
24bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24bc0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
24bd0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
24be0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
24bf0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
24c00 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24c10 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
24c20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
24c30 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
24c40 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
24c50 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
24c60 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
24c70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
24c80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
24c90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
24ca0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
24cb0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
24cc0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
24cd0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
24ce0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
24cf0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
24d00 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
24d10 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
24d20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
24d30 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
24d40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24d50 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
24d60 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
24d70 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
24d80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
24d90 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
24da0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
24db0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
24dc0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
24dd0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
24de0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
24df0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
24e00 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
24e10 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
24e20 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
24e30 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
24e40 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
24e50 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
24e60 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
24e70 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
24e80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
24e90 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
24ea0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
24eb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
24ec0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
24ed0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
24ee0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
24ef0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
24f00 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
24f10 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
24f20 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
24f30 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
24f40 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
24f50 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
24f60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
24f70 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
24f80 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
24f90 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
24fa0 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
24fb0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
24fc0 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
24fd0 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
24fe0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
24ff0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
25000 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
25010 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
25020 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
25030 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
25040 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
25050 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
25060 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
25070 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
25080 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
25090 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
250a0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
250b0 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
250c0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
250d0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
250e0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
250f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25100 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
25110 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
25120 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
25130 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
25140 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
25150 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
25160 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
25170 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
25180 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
25190 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
251a0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
251b0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
251c0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
251d0 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
251e0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
251f0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
25200 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
25210 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
25220 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
25230 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
25240 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
25250 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
25260 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
25270 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
25280 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
25290 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
252a0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
252b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
252c0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
252d0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
252e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
252f0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
25300 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
25310 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
25320 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
25330 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
25340 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
25350 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
25360 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
25370 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
25380 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
25390 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
253a0 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
253b0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
253c0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
253d0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
253e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
253f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
25400 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
25410 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
25420 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
25430 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
25440 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
25450 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
25460 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
25470 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
25480 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
25490 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
254a0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
254b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
254c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
254d0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
254e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
254f0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
25500 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
25510 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
25520 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
25530 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
25540 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
25550 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
25560 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
25570 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
25580 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
25590 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
255a0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
255b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
255c0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
255d0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
255e0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
255f0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
25600 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
25610 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
25620 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
25630 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25640 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
25650 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
25660 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
25670 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
25680 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
25690 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
256a0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
256b0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
256c0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
256d0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
256e0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
256f0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
25700 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
25710 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
25720 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
25730 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
25740 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
25750 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
25760 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
25770 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
25780 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
25790 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
257a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
257b0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
257c0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
257d0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
257e0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
257f0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
25800 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
25810 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
25820 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
25830 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
25840 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
25850 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
25860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
25870 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
25880 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
25890 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
258a0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
258b0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
258c0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
258d0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
258e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
258f0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
25900 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
25910 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
25920 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
25930 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
25940 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
25950 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
25960 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
25970 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
25980 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
25990 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
259a0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
259b0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
259c0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
259d0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
259e0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
259f0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
25a00 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
25a10 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
25a20 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
25a30 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
25a40 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
25a50 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
25a60 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
25a70 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
25a80 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
25a90 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
25aa0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
25ab0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
25ac0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
25ad0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
25ae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25af0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
25b00 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
25b10 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
25b20 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
25b30 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
25b40 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
25b50 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
25b60 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
25b70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
25b80 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
25b90 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
25ba0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
25bb0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
25bc0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
25bd0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
25be0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
25bf0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
25c00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
25c10 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
25c20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
25c30 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
25c40 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
25c50 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25c60 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
25c70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25c80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
25c90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
25ca0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
25cb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
25cc0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
25cd0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
25ce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
25cf0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25d00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
25d10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
25d20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
25d30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
25d40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25d50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
25d60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
25d70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
25d80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
25d90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
25da0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
25db0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
25dc0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
25dd0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25de0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
25df0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
25e00 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
25e10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
25e20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
25e30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
25e40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
25e50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
25e60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
25e70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25e80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25e90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
25ea0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
25eb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
25ec0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
25ed0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
25ee0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
25ef0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25f00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25f10 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
25f20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
25f30 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
25f40 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
25f50 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
25f60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25f70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25f80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25f90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25fa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25fb0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25fc0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25fd0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25fe0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
25ff0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26000 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26010 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
26020 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26030 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
26040 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
26050 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
26060 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26070 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
26080 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
26090 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
260a0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
260b0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
260c0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
260d0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
260e0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
260f0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26100 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26110 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26120 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
26130 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26140 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26150 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26160 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
26170 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
26180 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
26190 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
261a0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
261b0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
261c0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
261d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
261e0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
261f0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
26200 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26210 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
26220 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
26230 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
26240 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26250 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
26260 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26270 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
26280 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
26290 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
262a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
262b0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
262c0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
262d0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
262e0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
262f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26300 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
26310 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
26320 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
26330 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
26340 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26350 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
26360 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
26370 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
26380 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
26390 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
263a0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
263b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
263c0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
263d0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
263e0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
263f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
26400 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
26410 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
26420 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
26430 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
26440 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
26450 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
26460 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
26470 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
26480 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
26490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
264a0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
264b0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
264c0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
264d0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
264e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
264f0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
26500 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
26510 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
26520 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
26530 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
26540 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
26550 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
26560 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
26570 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
26580 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
26590 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
265a0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
265b0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
265c0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
265d0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
265e0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
265f0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
26600 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
26610 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
26620 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
26630 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26640 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
26650 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
26660 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
26670 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
26680 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
26690 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
266a0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
266b0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
266c0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
266d0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
266e0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
266f0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
26700 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
26710 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
26720 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
26730 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26740 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
26750 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
26760 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
26770 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
26780 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
26790 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
267a0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
267b0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
267c0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
267d0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
267e0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
267f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
26800 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
26810 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
26820 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26830 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
26840 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
26850 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
26860 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
26870 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
26880 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
26890 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
268a0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
268b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
268c0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
268d0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
268e0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
268f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
26900 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
26910 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
26920 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
26930 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
26940 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
26950 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
26960 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
26970 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
26980 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
26990 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
269a0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
269b0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
269c0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
269d0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
269e0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
269f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
26a00 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
26a10 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
26a20 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
26a30 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
26a40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
26a50 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26a60 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
26a70 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
26a80 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
26a90 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
26aa0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
26ab0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
26ac0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
26ad0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
26ae0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
26af0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
26b00 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
26b10 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
26b20 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
26b30 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
26b40 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
26b50 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
26b60 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
26b70 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
26b80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
26b90 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
26ba0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
26bb0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
26bc0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
26bd0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
26be0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
26bf0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
26c00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26c10 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
26c20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
26c30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26c40 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
26c50 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
26c60 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
26c70 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
26c80 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
26c90 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
26ca0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
26cb0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
26cc0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
26cd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26ce0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
26cf0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
26d00 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
26d10 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
26d20 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
26d30 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
26d40 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
26d50 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
26d60 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
26d70 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
26d80 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
26d90 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
26da0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
26db0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
26dc0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
26dd0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
26de0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
26df0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
26e00 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
26e10 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
26e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
26e30 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
26e40 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
26e50 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
26e60 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
26e70 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
26e80 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
26e90 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
26ea0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
26eb0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
26ec0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
26ed0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
26ee0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
26ef0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
26f00 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26f10 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
26f20 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
26f30 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
26f40 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26f50 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
26f60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
26f70 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
26f80 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
26f90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
26fa0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
26fb0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
26fc0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
26fd0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
26fe0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
26ff0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
27000 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
27010 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
27020 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
27030 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
27040 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
27050 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
27060 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
27070 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
27080 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
27090 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
270a0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
270b0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
270c0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
270d0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
270e0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
270f0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
27100 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
27110 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
27120 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
27130 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
27140 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
27150 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27160 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
27170 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
27180 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
27190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
271a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
271b0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
271c0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
271d0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
271e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
271f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27200 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
27210 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
27220 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27230 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
27240 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
27250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
27260 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
27270 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
27280 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27290 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
272a0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
272b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
272c0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
272d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
272e0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
272f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
27300 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
27310 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
27320 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
27330 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
27340 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27350 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
27360 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
27370 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
27380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27390 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
273a0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
273b0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
273c0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
273d0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
273e0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
273f0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
27400 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
27410 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
27420 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
27430 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
27440 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
27450 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
27460 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
27470 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
27480 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27490 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
274a0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
274b0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
274c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
274d0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
274e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
274f0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
27500 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
27510 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27520 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
27530 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27540 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
27550 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
27560 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
27570 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
27580 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
27590 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
275a0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
275b0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
275c0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
275d0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
275e0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
275f0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
27600 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
27610 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
27620 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
27630 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
27640 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
27650 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
27660 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
27670 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
27680 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
27690 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
276a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
276b0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
276c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
276d0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
276e0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
276f0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
27700 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
27710 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
27720 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
27730 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
27740 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
27750 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
27760 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
27770 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
27780 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
27790 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
277a0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
277b0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
277c0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
277d0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
277e0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
277f0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
27800 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
27810 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
27820 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
27830 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
27840 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
27850 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
27860 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
27870 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
27880 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27890 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
278a0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
278b0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
278c0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
278d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
278e0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
278f0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
27900 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
27910 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
27920 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
27930 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27940 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
27950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
27960 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
27970 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
27980 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
27990 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
279a0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
279b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
279c0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
279d0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
279e0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
279f0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
27a00 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
27a10 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
27a20 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
27a30 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
27a40 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
27a50 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
27a60 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
27a70 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
27a80 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
27a90 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
27aa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27ab0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
27ac0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
27ad0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
27ae0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
27af0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
27b00 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
27b10 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
27b20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
27b30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
27b40 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
27b50 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
27b60 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27b70 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
27b80 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
27b90 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
27ba0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
27bb0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
27bc0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
27bd0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
27be0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
27bf0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
27c00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27c10 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
27c20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
27c30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27c40 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
27c50 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
27c60 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
27c70 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
27c80 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
27c90 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
27ca0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
27cb0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
27cc0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
27cd0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
27ce0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
27cf0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
27d00 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
27d10 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
27d20 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
27d30 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
27d40 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
27d50 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
27d60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
27d70 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
27d80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27d90 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
27da0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
27db0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
27dc0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
27dd0 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
27de0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
27df0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
27e00 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
27e10 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
27e20 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
27e30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27e40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
27e50 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
27e60 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
27e70 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
27e80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
27e90 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
27ea0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27eb0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
27ec0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27ed0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
27ee0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
27ef0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
27f00 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
27f10 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
27f20 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
27f30 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
27f40 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
27f50 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
27f60 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
27f70 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
27f80 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
27f90 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
27fa0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
27fb0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
27fc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
27fd0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
27fe0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
27ff0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
28000 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
28010 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
28020 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
28030 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
28040 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
28050 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
28060 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
28070 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
28080 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
28090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
280a0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
280b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
280c0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
280d0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
280e0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
280f0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
28100 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
28110 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
28120 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
28130 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
28140 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
28150 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
28160 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
28170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28180 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
28190 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
281a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
281b0 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
281c0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
281d0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
281e0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
281f0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
28200 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
28210 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
28220 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
28230 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
28240 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
28250 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
28260 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
28270 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
28280 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
28290 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
282a0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
282b0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
282c0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
282d0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
282e0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
282f0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
28300 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
28310 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
28320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
28330 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
28340 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
28350 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
28360 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
28370 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
28380 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
28390 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
283a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
283b0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
283c0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
283d0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
283e0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
283f0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
28400 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
28410 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
28420 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
28430 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
28440 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
28450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
28460 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
28470 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
28480 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
28490 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
284a0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
284b0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
284c0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
284d0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
284e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
284f0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
28500 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
28510 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
28520 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
28530 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
28540 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
28550 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
28560 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
28570 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
28580 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
28590 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
285a0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
285b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
285c0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
285d0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
285e0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
285f0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
28600 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
28610 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28620 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
28630 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
28640 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
28650 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
28660 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
28670 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
28680 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
28690 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
286a0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
286b0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
286c0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
286d0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
286e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
286f0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
28700 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
28710 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
28720 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
28730 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
28740 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
28750 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
28760 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
28770 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
28780 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
28790 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
287a0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
287b0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
287c0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
287d0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
287e0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
287f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28800 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28810 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
28820 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28830 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
28840 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
28850 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
28860 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
28870 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
28880 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
28890 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
288a0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
288b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
288c0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
288d0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
288e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
288f0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
28900 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
28910 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28920 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
28930 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28940 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
28950 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
28960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28980 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
28990 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
289a0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
289b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
289c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
289d0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
289e0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
289f0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
28a00 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
28a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28a20 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
28a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28a40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
28a50 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
28a60 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
28a70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28a80 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
28a90 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
28aa0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
28ab0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
28ac0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
28ad0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
28ae0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
28af0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
28b00 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
28b10 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
28b20 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
28b30 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
28b40 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
28b50 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
28b60 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
28b70 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
28b80 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
28b90 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
28ba0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
28bb0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
28bc0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
28bd0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
28be0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
28bf0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
28c00 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
28c10 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
28c20 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
28c30 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
28c40 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
28c50 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
28c60 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
28c70 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
28c80 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
28c90 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
28ca0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
28cb0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
28cc0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
28cd0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
28ce0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
28cf0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
28d00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28d10 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
28d20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28d30 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
28d40 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
28d50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28d60 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
28d70 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
28d80 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
28d90 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
28da0 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
28db0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28dc0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
28dd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
28de0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
28df0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
28e00 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
28e10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28e20 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
28e30 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
28e40 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
28e50 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
28e60 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
28e70 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
28e80 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
28e90 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
28ea0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
28eb0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
28ec0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
28ed0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
28ee0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
28ef0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
28f00 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
28f10 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
28f20 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
28f30 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
28f40 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
28f50 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
28f60 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
28f70 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
28f80 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
28f90 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
28fa0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
28fb0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
28fc0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
28fd0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
28fe0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
28ff0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
29000 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
29010 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
29020 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
29030 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
29040 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
29050 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
29060 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
29070 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
29080 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
29090 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
290a0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
290b0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
290c0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
290d0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
290e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
290f0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29100 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29110 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29120 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29130 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29140 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29150 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
29160 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29170 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29180 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29190 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
291a0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
291b0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
291c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
291d0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
291e0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
291f0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
29200 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
29210 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
29220 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
29230 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
29240 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
29250 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
29260 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
29270 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
29280 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29290 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
292a0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
292b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
292c0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
292d0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
292e0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
292f0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
29300 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
29310 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
29320 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
29330 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
29340 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
29350 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
29360 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
29370 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29390 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
293a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
293b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
293c0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
293d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
293e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
293f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29400 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29410 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
29420 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
29430 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
29440 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
29450 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
29460 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
29470 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
29480 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
29490 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
294a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
294b0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
294c0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
294d0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
294e0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
294f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
29500 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
29510 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
29520 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
29530 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
29540 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
29550 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
29560 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29570 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29580 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
29590 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
295a0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
295b0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
295c0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
295d0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
295e0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
295f0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
29600 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29610 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
29620 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
29630 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
29640 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
29650 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
29660 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
29670 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29680 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
29690 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
296a0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
296b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
296c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
296d0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
296e0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
296f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
29700 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
29710 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
29720 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
29730 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
29740 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
29750 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29760 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
29770 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
29780 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
29790 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
297a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
297b0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
297c0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
297d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
297e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
297f0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
29800 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
29810 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
29820 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
29830 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29840 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
29850 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
29860 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29870 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
29880 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29890 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
298a0 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
298b0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
298c0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
298d0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
298e0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
298f0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
29900 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29910 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
29920 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
29930 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29940 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
29950 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
29960 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
29970 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
29980 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
29990 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
299a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
299b0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
299c0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
299d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
299e0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
299f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
29a00 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
29a10 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
29a20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
29a30 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
29a40 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
29a50 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
29a60 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
29a70 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
29a80 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
29a90 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
29aa0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
29ab0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
29ac0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
29ad0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
29ae0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
29af0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
29b00 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
29b10 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
29b20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
29b30 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
29b40 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
29b50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
29b60 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
29b70 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
29b80 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
29b90 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
29ba0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
29bb0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
29bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29bd0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29be0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
29bf0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29c00 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
29c10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29c20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
29c30 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
29c40 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
29c50 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
29c60 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
29c70 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
29c80 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
29c90 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
29ca0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
29cb0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
29cc0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
29cd0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
29ce0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
29cf0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
29d00 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
29d10 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
29d20 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
29d30 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
29d40 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
29d50 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
29d60 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
29d70 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
29d80 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
29d90 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
29da0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
29db0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
29dc0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
29dd0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
29de0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
29df0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
29e00 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29e10 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
29e20 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
29e30 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
29e40 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
29e50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29e60 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
29e70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29e80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
29e90 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
29ea0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
29eb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29ec0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
29ed0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
29ee0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
29ef0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
29f00 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
29f10 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
29f20 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
29f30 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
29f40 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
29f50 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
29f60 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
29f70 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
29f80 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
29f90 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
29fa0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
29fb0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
29fc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29fd0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
29fe0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
29ff0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2a000 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2a010 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2a020 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2a030 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2a040 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2a050 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2a060 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2a070 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2a080 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2a090 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2a0a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2a0b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2a0c0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2a0d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2a0e0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2a0f0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2a100 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2a110 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2a120 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2a130 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2a140 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2a150 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2a160 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2a170 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2a180 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2a190 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2a1a0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2a1b0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2a1c0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2a1d0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2a1e0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2a1f0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2a200 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2a210 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2a220 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2a230 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2a240 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2a250 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2a260 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2a270 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2a280 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2a290 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2a2a0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2a2b0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2a2c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2a2d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2a2e0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2a2f0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2a300 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2a310 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2a320 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2a330 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2a340 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2a350 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2a360 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a370 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2a380 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2a390 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2a3a0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2a3b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2a3c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2a3d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2a3e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2a3f0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2a400 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2a410 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2a420 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2a430 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a440 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2a450 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2a460 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2a470 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a480 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2a490 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a4a0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2a4b0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2a4c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2a4d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a4e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2a4f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2a500 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2a510 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a520 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2a530 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a540 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2a550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a560 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2a570 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a580 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2a5a0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2a5b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2a5c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a5d0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2a5e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a5f0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2a600 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2a610 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2a620 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2a630 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2a640 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2a650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a660 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2a670 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2a680 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2a690 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2a6a0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2a6b0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2a6c0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2a6d0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2a6e0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2a6f0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2a700 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2a710 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2a720 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2a730 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2a740 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2a750 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2a760 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2a770 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2a780 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2a790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a7a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2a7b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2a7c0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2a7d0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2a7e0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2a7f0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2a800 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2a810 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2a820 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2a830 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2a840 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2a850 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2a860 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2a870 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2a880 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2a890 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2a8a0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2a8b0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2a8c0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2a8d0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2a8e0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2a8f0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2a900 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2a910 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2a920 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2a930 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2a940 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2a950 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2a960 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2a970 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2a980 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2a990 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2a9a0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2a9b0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2a9c0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2a9d0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2a9e0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2a9f0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2aa00 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2aa10 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2aa20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2aa30 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2aa40 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2aa50 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2aa60 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2aa70 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2aa80 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2aa90 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2aaa0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2aab0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2aac0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2aad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2aae0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2aaf0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2ab00 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2ab10 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2ab20 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2ab30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ab40 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2ab50 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2ab60 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2ab70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ab80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2ab90 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2aba0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2abb0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2abc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2abd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2abe0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2abf0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2ac00 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2ac10 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2ac20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2ac30 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2ac40 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2ac50 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ac60 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2ac70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2ac80 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2ac90 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2aca0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2acb0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2acc0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2acd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ace0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2acf0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ad00 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2ad10 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2ad20 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2ad30 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2ad40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2ad50 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2ad60 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2ad70 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2ad80 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2ad90 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2ada0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2adb0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2adc0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2add0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2ade0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2adf0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2ae00 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2ae10 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2ae20 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2ae30 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2ae40 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2ae50 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2ae60 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2ae70 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2ae80 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2ae90 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2aea0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2aeb0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2aec0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2aed0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2aee0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2aef0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2af00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2af10 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2af20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2af30 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2af40 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2af50 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2af60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2af70 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2af80 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2af90 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2afa0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2afb0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2afc0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2afd0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2afe0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2aff0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2b000 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2b010 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2b020 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2b030 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2b040 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2b050 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2b060 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2b070 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2b080 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2b090 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2b0a0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2b0b0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2b0c0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2b0d0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2b0e0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2b0f0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2b100 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2b110 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2b120 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2b130 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2b140 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2b150 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2b160 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2b170 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2b180 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2b190 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2b1a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2b1b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2b1c0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2b1d0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2b1e0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2b1f0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2b200 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2b210 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2b220 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2b230 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2b240 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2b250 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2b260 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2b270 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2b280 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2b290 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2b2a0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2b2b0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2b2c0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2b2d0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2b2e0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2b2f0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2b300 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2b310 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2b320 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2b330 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2b340 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2b350 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2b360 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2b370 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2b380 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2b390 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2b3a0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2b3b0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2b3c0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2b3d0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2b3e0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2b3f0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2b400 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2b410 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b420 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2b430 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b440 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2b450 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2b460 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2b470 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2b480 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2b490 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2b4a0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2b4b0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2b4c0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2b4d0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2b4e0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2b4f0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2b500 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2b510 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b520 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2b530 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2b540 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2b550 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2b560 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2b570 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2b580 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2b590 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2b5a0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2b5b0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2b5c0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2b5d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b5e0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2b5f0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2b600 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2b610 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2b620 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2b630 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2b640 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2b650 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2b660 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2b670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2b680 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2b690 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2b6a0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2b6b0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2b6c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2b6d0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2b6e0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2b6f0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2b700 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2b710 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2b720 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b730 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2b740 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b750 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2b760 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2b770 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2b780 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2b790 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2b7a0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2b7b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2b7c0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2b7d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b7e0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2b7f0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2b800 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2b810 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2b820 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2b830 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2b840 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2b850 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2b860 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2b870 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2b880 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2b890 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2b8a0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2b8b0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2b8c0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2b8d0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2b8e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2b8f0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2b900 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2b910 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2b920 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2b930 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2b940 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2b950 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2b960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2b970 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2b980 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2b990 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2b9a0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2b9b0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2b9c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2b9d0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2b9e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2b9f0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2ba00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ba10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2ba20 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2ba30 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2ba40 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2ba50 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2ba60 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2ba70 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2ba80 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2ba90 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2baa0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2bab0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2bac0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2bad0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2bae0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2baf0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2bb00 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2bb10 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2bb20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bb30 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2bb40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2bb50 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2bb60 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2bb70 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2bb80 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2bb90 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2bba0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2bbb0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2bbc0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2bbd0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2bbe0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2bbf0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2bc00 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2bc10 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2bc20 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2bc30 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2bc40 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2bc50 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2bc60 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2bc70 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2bc80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bc90 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2bca0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bcb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2bcc0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2bcd0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2bce0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2bcf0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2bd00 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2bd10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bd20 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2bd30 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2bd40 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2bd50 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2bd60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2bd70 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2bd80 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2bd90 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2bda0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2bdb0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2bdc0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2bdd0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2bde0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2bdf0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2be00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2be10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2be20 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2be30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2be40 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2be50 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2be60 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2be70 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2be80 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2be90 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2bea0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2beb0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2bec0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2bed0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2bee0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2bef0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2bf00 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2bf10 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2bf20 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2bf30 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2bf40 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2bf50 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2bf60 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2bf70 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2bf80 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2bf90 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2bfa0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2bfb0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2bfc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2bfd0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2bfe0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2bff0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c000 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2c010 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2c020 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2c030 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2c040 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2c050 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2c060 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2c070 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2c080 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2c090 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2c0a0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2c0b0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2c0c0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2c0d0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2c0e0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2c0f0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2c100 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2c110 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2c120 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2c130 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2c140 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2c150 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2c160 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2c170 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2c180 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2c190 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2c1a0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2c1b0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2c1c0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2c1d0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2c1e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c1f0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2c200 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2c210 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2c220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c230 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2c240 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2c250 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2c260 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2c270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2c280 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2c290 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2c2a0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2c2b0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2c2c0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2c2d0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2c2e0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2c2f0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2c300 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2c310 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2c320 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2c330 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2c340 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2c350 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2c360 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2c370 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2c380 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c390 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2c3a0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2c3b0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2c3c0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2c3d0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2c3e0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2c3f0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2c400 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2c410 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2c420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c430 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2c440 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2c450 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2c460 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2c470 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2c480 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c490 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2c4a0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2c4b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2c4c0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2c4d0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2c4e0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2c4f0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2c500 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2c510 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2c520 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2c530 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2c540 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2c550 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2c560 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2c570 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2c580 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2c590 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2c5a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2c5b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2c5c0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2c5d0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2c5e0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2c5f0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2c600 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2c610 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2c620 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2c630 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2c640 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2c650 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2c660 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2c670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c680 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2c690 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2c6a0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2c6b0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2c6c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c6d0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2c6e0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2c6f0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2c700 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2c710 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2c720 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c730 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2c740 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2c750 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2c760 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2c770 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2c780 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2c790 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2c7a0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2c7b0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2c7c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2c7d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c7e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2c7f0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2c800 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2c810 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2c820 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2c830 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2c840 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2c850 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2c860 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c870 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2c880 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2c890 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2c8a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2c8b0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2c8c0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2c8d0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2c8e0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2c8f0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2c900 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2c910 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2c920 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2c930 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2c940 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2c950 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2c960 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2c970 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2c980 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c990 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2c9a0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2c9b0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2c9c0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2c9d0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2c9e0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2c9f0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2ca00 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2ca10 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ca20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ca30 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2ca40 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2ca50 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2ca60 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2ca70 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2ca80 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2ca90 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2caa0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2cab0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2cac0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2cad0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2cae0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2caf0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2cb00 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2cb10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2cb20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2cb30 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2cb40 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2cb50 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2cb60 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2cb70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2cb80 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2cb90 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2cba0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2cbb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2cbc0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2cbd0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2cbe0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2cbf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cc00 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2cc10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2cc20 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2cc30 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2cc40 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2cc50 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2cc60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2cc70 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2cc80 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2cc90 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2cca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ccb0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2ccc0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2ccd0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2cce0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2ccf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2cd00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cd10 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2cd20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2cd30 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2cd40 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2cd50 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2cd60 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2cd70 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2cd80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cd90 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2cda0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2cdb0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2cdc0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2cdd0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2cde0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2cdf0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2ce00 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2ce10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ce20 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2ce30 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2ce40 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2ce50 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2ce60 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ce70 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2ce80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ce90 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2cea0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ceb0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2cec0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ced0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2cee0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2cef0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2cf00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2cf10 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2cf20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2cf30 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2cf40 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2cf50 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2cf60 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2cf70 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2cf80 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2cf90 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2cfa0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2cfb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2cfc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2cfd0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2cfe0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2cff0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2d000 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2d010 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2d020 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2d030 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2d040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d050 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2d060 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d070 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2d080 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2d090 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2d0a0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2d0b0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2d0c0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2d0d0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2d0e0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2d0f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2d100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2d110 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2d120 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d130 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2d140 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2d150 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d160 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2d170 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d180 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2d190 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2d1a0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2d1b0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2d1c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d1d0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2d1e0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2d1f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d200 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2d210 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2d220 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2d230 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2d240 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2d250 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2d260 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2d270 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2d280 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2d290 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2d2a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d2b0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2d2c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2d2d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d2e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2d2f0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2d300 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2d310 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2d320 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2d330 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2d340 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2d350 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2d360 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2d370 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2d380 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d390 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2d3a0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2d3b0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2d3c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2d3d0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2d3e0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2d3f0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2d400 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2d410 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2d420 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2d430 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2d440 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2d450 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2d460 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2d470 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2d480 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2d490 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2d4a0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2d4b0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2d4c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2d4d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2d4e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2d4f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2d500 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2d510 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2d520 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2d530 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2d540 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2d550 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2d560 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2d570 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2d580 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2d590 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2d5a0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2d5b0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2d5c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2d5d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2d5e0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2d5f0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2d600 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2d610 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2d620 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2d630 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2d640 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2d650 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2d660 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2d670 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2d680 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2d690 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2d6a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d6b0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2d6c0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2d6d0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2d6e0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2d6f0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2d700 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2d710 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2d720 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2d730 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2d740 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2d750 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2d760 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2d770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2d780 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2d790 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2d7a0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2d7b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2d7c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2d7d0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2d7e0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2d7f0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2d800 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2d810 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2d820 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2d830 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2d840 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2d850 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d860 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2d870 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2d880 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2d890 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2d8a0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
2d8b0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
2d8c0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
2d8d0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
2d8e0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
2d8f0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
2d900 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
2d910 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
2d920 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
2d930 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
2d940 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
2d950 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
2d960 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
2d970 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
2d980 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
2d990 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
2d9a0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
2d9b0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
2d9c0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
2d9d0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d9e0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
2d9f0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
2da00 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2da10 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
2da20 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2da30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
2da40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2da50 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
2da60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2da70 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
2da80 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
2da90 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
2daa0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
2dab0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
2dac0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
2dad0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
2dae0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2daf0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2db00 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
2db10 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2db20 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
2db30 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2db40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2db50 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
2db60 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
2db70 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
2db80 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2db90 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
2dba0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2dbb0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2dbc0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
2dbd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dbe0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
2dbf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dc00 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2dc10 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2dc20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2dc30 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2dc40 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
2dc50 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2dc60 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
2dc70 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2dc80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2dc90 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2dca0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2dcb0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2dcc0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2dcd0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2dce0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
2dcf0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2dd00 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
2dd10 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2dd20 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2dd30 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2dd40 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2dd50 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2dd60 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2dd70 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2dd80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2dd90 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2dda0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2ddb0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
2ddc0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
2ddd0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
2dde0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
2ddf0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
2de00 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
2de10 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
2de20 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
2de30 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
2de40 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
2de50 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
2de60 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
2de70 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
2de80 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
2de90 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
2dea0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
2deb0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
2dec0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
2ded0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
2dee0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
2def0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2df00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
2df10 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2df20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2df30 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2df40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2df50 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2df60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2df70 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2df80 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2df90 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
2dfa0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2dfb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
2dfc0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2dfd0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2dfe0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
2dff0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
2e000 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
2e010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e020 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
2e030 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2e040 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
2e050 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
2e060 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
2e070 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
2e080 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e090 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
2e0a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e0b0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
2e0c0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
2e0d0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
2e0e0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
2e0f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e100 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2e110 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
2e120 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
2e130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e140 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
2e150 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
2e160 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e170 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
2e180 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
2e190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e1a0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
2e1b0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2e1c0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2e1d0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2e1e0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2e1f0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2e200 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2e210 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2e220 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e230 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2e240 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2e250 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
2e260 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2e270 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2e280 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2e290 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2e2a0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2e2b0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2e2c0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2e2d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e2e0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2e2f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2e300 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2e310 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2e320 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2e330 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2e340 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2e350 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2e360 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2e370 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2e380 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2e390 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2e3a0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2e3b0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2e3c0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2e3d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2e3e0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2e3f0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2e400 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2e410 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2e420 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2e430 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2e440 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2e450 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e460 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2e470 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e480 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2e490 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e4a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e4b0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2e4c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e4d0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2e4e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2e4f0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2e500 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2e510 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e520 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2e530 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2e540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e550 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2e560 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2e570 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2e580 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e590 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2e5a0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2e5b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2e5c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e5d0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2e5e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2e5f0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2e600 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e620 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2e630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e640 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2e650 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2e660 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2e670 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e690 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2e6a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e6b0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2e6c0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2e6d0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2e6e0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2e6f0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2e700 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2e710 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2e720 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2e730 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2e740 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2e750 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2e760 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2e770 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2e780 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2e790 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2e7a0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2e7b0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2e7c0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2e7d0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2e7e0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2e7f0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e800 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2e810 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2e820 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2e830 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2e840 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2e850 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2e860 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2e870 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2e880 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2e890 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2e8a0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2e8b0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2e8c0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2e8d0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2e8e0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2e8f0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2e900 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2e910 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2e920 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2e930 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e940 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2e950 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2e960 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2e970 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2e980 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2e990 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2e9a0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2e9b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2e9c0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2e9d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2e9e0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2e9f0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2ea00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ea10 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2ea20 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2ea30 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2ea40 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2ea50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ea60 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2ea70 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2ea80 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2ea90 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2eaa0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2eab0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2eac0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2ead0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2eae0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2eaf0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2eb00 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2eb10 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2eb20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2eb30 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2eb40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2eb50 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2eb60 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2eb70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2eb80 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2eb90 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2eba0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2ebb0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2ebc0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2ebd0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2ebe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2ebf0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2ec00 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2ec10 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2ec20 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2ec30 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2ec40 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2ec50 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2ec60 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2ec70 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2ec80 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2ec90 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2eca0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2ecb0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2ecc0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2ecd0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2ece0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2ecf0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2ed00 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2ed10 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2ed20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ed30 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2ed40 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2ed50 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2ed60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ed70 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2ed80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ed90 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2eda0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2edb0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2edc0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2edd0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2ede0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2edf0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2ee00 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2ee10 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2ee20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2ee30 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2ee40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2ee50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2ee60 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2ee70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2ee80 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2ee90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eea0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2eeb0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2eec0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2eed0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2eee0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2eef0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2ef00 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2ef10 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2ef20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2ef30 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
2ef40 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2ef50 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2ef60 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2ef70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2ef80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ef90 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2efa0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2efb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2efc0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2efd0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2efe0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2eff0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2f000 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2f010 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2f020 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2f030 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2f040 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2f050 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2f060 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2f070 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2f080 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2f090 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2f0a0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2f0b0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2f0c0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2f0d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2f0e0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2f0f0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2f100 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2f110 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2f120 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2f130 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2f140 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2f150 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2f160 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2f170 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2f180 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2f190 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2f1a0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2f1b0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2f1c0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2f1d0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2f1e0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2f1f0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2f200 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2f210 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2f220 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
2f230 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2f240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f250 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2f260 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2f270 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2f280 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
2f290 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
2f2a0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
2f2b0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2f2c0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
2f2d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2f2e0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2f2f0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
2f300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f310 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
2f320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2f330 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2f340 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2f350 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2f360 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2f370 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
2f380 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2f390 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2f3a0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
2f3b0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
2f3c0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
2f3d0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
2f3e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
2f3f0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2f400 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
2f410 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
2f420 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
2f430 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
2f440 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
2f450 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2f460 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2f470 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2f480 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2f490 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2f4a0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
2f4b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2f4c0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
2f4d0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
2f4e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2f4f0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
2f500 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2f510 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
2f520 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2f530 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
2f540 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f550 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2f560 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2f570 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
2f580 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
2f590 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
2f5a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2f5b0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
2f5c0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
2f5d0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
2f5e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
2f5f0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
2f600 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
2f610 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2f620 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
2f630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
2f640 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
2f650 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
2f660 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
2f670 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
2f680 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
2f690 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
2f6a0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
2f6b0 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
2f6c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2f6d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2f6e0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
2f6f0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
2f700 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2f710 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2f720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2f730 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2f740 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2f750 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2f760 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
2f770 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
2f780 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2f790 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f7a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2f7b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2f7c0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2f7d0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2f7e0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2f7f0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2f800 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2f810 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
2f820 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f830 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f840 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
2f850 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
2f860 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
2f870 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
2f880 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2f890 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
2f8a0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
2f8b0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
2f8c0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
2f8d0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
2f8e0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
2f8f0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
2f900 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
2f910 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
2f920 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
2f930 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
2f940 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2f950 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
2f960 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
2f970 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f980 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
2f990 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
2f9a0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
2f9b0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
2f9c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
2f9d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
2f9e0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
2f9f0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
2fa00 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2fa10 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2fa20 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2fa30 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2fa40 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2fa50 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2fa60 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2fa70 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
2fa80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2fa90 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2faa0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
2fab0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
2fac0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
2fad0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
2fae0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
2faf0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
2fb00 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
2fb10 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2fb20 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2fb30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fb40 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2fb50 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2fb60 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
2fb70 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2fb80 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
2fb90 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2fba0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2fbb0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2fbc0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
2fbd0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2fbe0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
2fbf0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
2fc00 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
2fc10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fc20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
2fc30 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
2fc40 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
2fc50 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
2fc60 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2fc70 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
2fc80 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
2fc90 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
2fca0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
2fcb0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
2fcc0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
2fcd0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
2fce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fcf0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
2fd00 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2fd10 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
2fd20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
2fd30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fd40 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
2fd50 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
2fd60 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2fd70 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
2fd80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
2fd90 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
2fda0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
2fdb0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
2fdc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2fdd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2fde0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
2fdf0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
2fe00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2fe10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fe20 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
2fe30 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
2fe40 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
2fe50 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2fe60 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2fe70 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
2fe80 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2fe90 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
2fea0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
2feb0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
2fec0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
2fed0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
2fee0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
2fef0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2ff00 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2ff10 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
2ff20 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2ff30 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2ff40 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2ff50 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
2ff60 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2ff70 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2ff80 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
2ff90 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
2ffa0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
2ffb0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2ffc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ffd0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
2ffe0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
2fff0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30000 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30010 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
30020 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
30030 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
30040 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
30050 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
30060 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
30070 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
30080 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
30090 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
300a0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
300b0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
300c0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
300d0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
300e0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
300f0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
30100 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
30110 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
30120 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
30130 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
30140 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
30150 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
30160 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30170 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
30180 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
30190 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
301a0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
301b0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
301c0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
301d0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
301e0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
301f0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
30200 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30210 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
30220 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
30230 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
30240 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
30250 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
30260 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
30270 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30280 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
30290 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
302a0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
302b0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
302c0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
302d0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
302e0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
302f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30300 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30310 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30320 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30330 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30340 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30350 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
30370 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30380 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30390 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
303a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
303b0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
303c0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
303d0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
303e0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
303f0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
30400 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30410 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30420 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
30430 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30440 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30450 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30460 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
30470 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
30480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30490 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
304a0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
304b0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
304c0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
304d0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
304e0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
304f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
30500 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30510 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30520 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30530 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30540 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30550 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30560 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
30570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30580 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
30590 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
305a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
305b0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
305c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
305d0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
305e0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
305f0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
30600 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
30610 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
30620 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
30630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30640 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
30650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30660 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
30670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30680 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
30690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
306a0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
306b0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
306c0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
306d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
306e0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
306f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
30700 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
30710 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
30720 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
30730 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
30740 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30750 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
30760 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
30770 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
30780 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
30790 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
307a0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
307b0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
307c0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
307d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
307e0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
307f0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
30800 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
30810 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
30820 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
30830 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30840 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
30850 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
30860 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
30870 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
30880 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
30890 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
308a0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
308b0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
308c0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
308d0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
308e0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
308f0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
30900 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30910 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30920 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
30930 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
30940 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30950 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
30960 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
30970 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30980 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
30990 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
309a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
309b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
309c0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
309d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
309e0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
309f0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
30a00 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
30a10 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
30a20 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
30a30 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
30a40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
30a50 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
30a60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
30a70 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
30a80 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
30a90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
30aa0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
30ab0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
30ac0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
30ad0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
30ae0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
30af0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
30b00 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
30b10 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
30b20 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
30b30 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
30b40 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
30b50 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
30b60 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
30b70 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
30b80 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
30b90 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
30ba0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
30bb0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
30bc0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
30bd0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
30be0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30bf0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
30c00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30c10 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
30c20 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
30c30 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
30c40 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
30c50 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
30c60 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
30c70 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
30c80 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
30c90 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
30ca0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
30cb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30cc0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
30cd0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
30ce0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
30cf0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
30d00 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
30d10 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
30d20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
30d30 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
30d40 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
30d50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
30d60 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
30d70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
30d80 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
30d90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30da0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
30db0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
30dc0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
30dd0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
30de0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30df0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
30e00 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
30e10 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
30e20 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
30e30 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
30e40 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
30e50 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
30e60 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
30e70 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
30e80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30e90 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
30ea0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30eb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
30ec0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
30ed0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
30ee0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
30ef0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
30f00 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
30f10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30f20 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
30f30 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
30f40 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
30f50 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
30f60 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
30f70 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
30f80 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
30f90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30fa0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
30fb0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
30fc0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30fd0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
30fe0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
30ff0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
31000 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
31010 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
31020 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
31030 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
31040 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
31050 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
31060 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
31070 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
31080 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
31090 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
310a0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
310b0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
310c0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
310d0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
310e0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
310f0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
31100 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
31110 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
31120 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
31130 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
31140 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
31150 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
31160 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
31170 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
31180 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
31190 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
311a0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
311b0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
311c0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
311d0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
311e0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
311f0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
31200 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
31210 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
31220 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
31230 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
31240 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
31250 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
31260 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
31270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
31280 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
31290 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
312a0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
312b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
312c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
312d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
312e0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
312f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31300 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
31310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31320 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
31330 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
31340 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
31350 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
31360 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
31370 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
31380 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
31390 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
313a0 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
313b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
313c0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
313d0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
313e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
313f0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31400 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31410 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
31420 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
31430 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
31440 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
31450 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
31460 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
31470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31480 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
31490 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
314a0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
314b0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
314c0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
314d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
314e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
314f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31500 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
31510 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31520 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31530 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
31540 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31550 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
31560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31570 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
31580 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31590 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
315a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
315b0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
315c0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
315d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
315e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
315f0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
31600 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
31610 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
31620 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
31630 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31640 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
31650 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
31660 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
31670 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
31680 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
31690 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
316a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
316b0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
316c0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
316d0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
316e0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
316f0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
31700 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
31710 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
31720 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
31730 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
31740 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
31750 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
31760 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
31770 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
31780 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
31790 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
317a0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
317b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
317c0 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
317d0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
317e0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
317f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31800 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
31810 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
31820 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
31830 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
31840 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
31850 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
31860 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
31870 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
31880 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
31890 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
318a0 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
318b0 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
318c0 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
318d0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
318e0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
318f0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
31900 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
31910 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
31920 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
31930 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
31940 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31950 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
31960 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
31970 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
31980 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
31990 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
319a0 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
319b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
319c0 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
319d0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
319e0 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74  r .** when first
319f0 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20   called if N is 
31a00 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
31a10 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
31a20 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
31a30 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
31a40 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
31a50 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
31a60 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
31a70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31a80 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
31a90 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
31aa0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
31ab0 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
31ac0 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
31ad0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
31ae0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
31af0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
31b00 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31b10 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
31b20 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
31b30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
31b40 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
31b50 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
31b60 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
31b70 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78  )^  Within the x
31b80 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20  Final callback, 
31b90 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20  it is customary 
31ba0 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e  to set.** N=0 in
31bb0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
31bc0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31bd0 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74  ext(C,N) so that
31be0 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73   no .** pointles
31bf0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
31c00 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a  ions occur..**.*
31c10 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
31c20 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
31c30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
31c40 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
31c50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31c60 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
31c70 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
31c80 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
31c90 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31ca0 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
31cb0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
31cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
31cd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31ce0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31cf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31d00 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
31d10 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
31d20 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
31d30 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
31d40 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
31d50 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
31d60 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
31d70 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
31d80 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
31d90 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
31da0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31db0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
31dc0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31dd0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31de0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
31df0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
31e00 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
31e10 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
31e20 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
31e30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31e40 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
31e50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31e60 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
31e70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
31e80 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
31e90 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
31ea0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
31eb0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
31ec0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
31ed0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
31ee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31ef0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
31f00 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
31f10 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
31f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
31f30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
31f40 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31f50 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31f60 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31f70 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31f80 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31f90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31fa0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31fb0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31fc0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
31fd0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
31fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31ff0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
32000 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
32010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32020 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
32030 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
32040 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
32050 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
32060 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
32070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32080 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
32090 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
320a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
320b0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
320c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
320d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
320e0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
320f0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
32100 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
32110 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
32120 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
32130 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
32140 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
32150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32170 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
32180 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
32190 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
321a0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
321b0 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
321c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
321d0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
321e0 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
321f0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
32200 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
32210 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
32220 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
32230 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
32240 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
32250 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
32260 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
32270 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
32280 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
32290 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
322a0 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
322b0 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
322c0 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
322d0 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
322e0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
322f0 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
32300 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
32310 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
32320 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
32330 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
32340 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
32350 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
32360 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
32370 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
32380 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
32390 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
323a0 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
323b0 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
323c0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
323d0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
323e0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
323f0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
32400 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
32410 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
32420 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32430 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
32440 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32450 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
32460 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
32470 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
32480 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
32490 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
324a0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
324b0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
324c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
324d0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
324e0 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
324f0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
32500 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
32510 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
32520 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
32530 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
32540 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
32550 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
32560 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
32570 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
32580 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
32590 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
325a0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
325b0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
325c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
325d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
325e0 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
325f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
32600 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
32610 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
32620 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
32630 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
32640 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
32650 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
32660 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
32670 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
32680 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
32690 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
326a0 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
326b0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
326c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
326d0 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
326e0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
326f0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32700 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32710 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
32720 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
32730 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
32740 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
32750 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
32760 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
32770 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
32780 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
32790 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
327a0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  <ul>.** <li> whe
327b0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
327c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
327d0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20  ameter changes, 
327e0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
327f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32800 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
32810 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
32820 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  led for the.**  
32830 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
32840 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  t, or.** <li> wh
32850 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  en sqlite3_set_a
32860 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f  uxdata() is invo
32870 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65  ked again on the
32880 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c   same parameter,
32890 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69   or.** <li> duri
328a0 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
328b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
328c0 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20  ata() call when 
328d0 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20  a memory .**    
328e0 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72    allocation err
328f0 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e  or occurs. </ul>
32900 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
32910 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e  e last bullet in
32920 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68   particular.  Th
32930 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69  e destructor X i
32940 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  n .** sqlite3_se
32950 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
32960 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  X) might be call
32970 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ed immediately, 
32980 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71  before the.** sq
32990 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
329a0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76  a() interface ev
329b0 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e  en returns.  Hen
329c0 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ce sqlite3_set_a
329d0 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75  uxdata().** shou
329e0 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61  ld be called nea
329f0 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  r the end of the
32a00 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32a10 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65  entation and the
32a20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  .** function imp
32a30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
32a40 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20  ld not make any 
32a50 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a  use of P after.*
32a60 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
32a70 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e  xdata() has been
32a80 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   called..**.** ^
32a90 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
32aa0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
32ab0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
32ac0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
32ad0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
32ae0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63  eters that are c
32af0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73  ompile-time cons
32b00 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  tants, including
32b10 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
32b20 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
32b30 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69  rs] and expressi
32b40 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f  ons composed fro
32b50 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a  m the same.)^.**
32b60 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32b70 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
32b80 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32b90 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
32ba0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
32bb0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
32bc0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
32bd0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
32be0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32bf0 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
32c00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32c10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32c20 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
32c30 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
32c40 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
32c50 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
32c60 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
32c70 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
32c80 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
32c90 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
32ca0 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
32cb0 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
32cc0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
32cd0 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
32ce0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
32cf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32d00 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
32d10 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
32d20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
32d30 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
32d40 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
32d50 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
32d60 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
32d70 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
32d80 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
32d90 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
32da0 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
32db0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
32dc0 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
32dd0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
32de0 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
32df0 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
32e00 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
32e10 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
32e20 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
32e30 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
32e40 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
32e50 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
32e60 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
32e70 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
32e80 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
32e90 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
32ea0 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a   C++ compilers..
32eb0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
32ec0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
32ed0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
32ee0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
32ef0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
32f00 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
32f10 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
32f20 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
32f30 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
32f40 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
32f50 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
32f60 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
32f70 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
32f80 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
32f90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32fa0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
32fb0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
32fc0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
32fd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
32fe0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
32ff0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
33000 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
33010 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
33020 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33030 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
33040 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
33050 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
33060 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
33070 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
33080 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
33090 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
330a0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
330b0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
330c0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
330d0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
330e0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
330f0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
33100 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
33110 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
33120 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
33130 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33150 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
33160 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33170 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
33180 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
33190 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
331a0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
331b0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
331c0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
331d0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
331e0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
331f0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
33200 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
33210 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
33220 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
33230 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33240 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
33250 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
33260 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
33270 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33280 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33290 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
332a0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
332b0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
332c0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
332d0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
332e0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
332f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
33300 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33310 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
33320 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
33330 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
33340 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33350 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33360 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
33370 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
33380 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
33390 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
333a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
333b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
333c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
333d0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
333e0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
333f0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
33400 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
33410 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
33420 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
33430 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
33440 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
33450 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
33460 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
33470 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
33480 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33490 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
334a0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
334b0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
334c0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
334d0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
334e0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
334f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33500 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
33510 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
33520 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
33530 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33540 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
33550 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
33560 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
33570 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
33580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
33590 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
335a0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
335b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
335c0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
335d0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
335e0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
335f0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
33600 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
33610 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
33620 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
33630 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
33640 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
33650 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
33660 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
33670 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
33680 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
33690 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
336a0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
336b0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
336c0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
336d0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
336e0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
336f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33700 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
33710 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33720 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
33730 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
33740 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
33750 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
33760 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
33770 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
33780 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
33790 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
337a0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
337b0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
337c0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
337d0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
337e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
337f0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
33800 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
33810 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
33820 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
33830 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
33840 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
33850 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
33860 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
33870 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
33880 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
33890 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
338a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
338b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
338c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
338d0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
338e0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
338f0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
33900 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
33910 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33920 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
33930 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
33940 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
33950 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
33960 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
33970 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
33980 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
33990 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
339a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
339b0 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
339c0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
339d0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
339e0 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
339f0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
33a00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
33a10 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
33a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33a30 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
33a40 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
33a50 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
33a60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33a70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33a80 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
33a90 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
33aa0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
33ab0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
33ac0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33ad0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
33ae0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
33af0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
33b00 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
33b10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33b20 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
33b30 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
33b40 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
33b50 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
33b60 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
33b70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33b80 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
33b90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33ba0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
33bb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33bc0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33bd0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
33be0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33bf0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
33c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33c10 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
33c20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33c30 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
33c40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33c50 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
33c60 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
33c70 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
33c80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33c90 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33ca0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
33cb0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
33cc0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
33cd0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
33ce0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
33cf0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
33d00 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
33d10 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
33d20 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
33d30 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
33d40 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
33d50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
33d60 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
33d70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
33d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33d90 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
33da0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
33db0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33dc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33dd0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33de0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
33df0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
33e00 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
33e10 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33e20 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
33e30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
33e40 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
33e50 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
33e60 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
33e70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
33e80 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
33e90 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
33ea0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
33eb0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
33ec0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
33ed0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
33ee0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33ef0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
33f00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33f10 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
33f20 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
33f30 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33f40 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
33f50 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
33f60 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
33f70 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
33f80 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
33f90 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
33fa0 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
33fb0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
33fc0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
33fd0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
33fe0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
33ff0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
34000 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
34010 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
34020 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
34030 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
34040 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
34050 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
34060 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
34070 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
34080 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
34090 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
340a0 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
340b0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
340c0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
340d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
340e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
340f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34100 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34110 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
34120 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
34130 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
34140 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
34150 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
34160 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
34170 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
34180 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
34190 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
341a0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
341b0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
341c0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
341d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
341e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
341f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
34200 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
34210 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
34220 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
34230 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
34240 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
34250 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
34260 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
34270 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
34280 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
34290 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
342a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
342b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
342c0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
342d0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
342e0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
342f0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
34300 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
34310 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
34320 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34330 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34340 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34350 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34360 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
34370 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
34380 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
34390 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
343a0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
343b0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
343c0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
343d0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
343e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
343f0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
34400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34410 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34420 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34430 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
34440 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34450 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34460 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
34470 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
34480 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34490 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
344a0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
344b0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
344c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
344d0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
344e0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
344f0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
34500 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
34510 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
34520 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
34530 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
34540 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
34550 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
34560 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
34570 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
34580 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
34590 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
345a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
345b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
345c0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
345d0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
345e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
345f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
34600 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
34610 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
34620 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34630 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
34640 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
34650 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
34660 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34670 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
34680 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
34690 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
346a0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
346b0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
346c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
346d0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
346e0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
346f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
34700 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
34710 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
34720 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
34730 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34740 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34750 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34760 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
34770 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
34780 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
34790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
347a0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
347b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
347c0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
347d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
347e0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
347f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34800 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
34810 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34820 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
34830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34840 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
34850 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
34860 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34870 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
34880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34890 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
348a0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
348b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
348c0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
348d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
348e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
348f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
34900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34910 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
34920 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
34930 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
34940 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
34950 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34960 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34970 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
34980 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34990 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
349a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
349b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
349c0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
349d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
349e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
349f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
34a00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34a10 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
34a20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34a30 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
34a40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34a50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34a60 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
34a70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
34a80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
34a90 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
34aa0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34ab0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
34ac0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
34ad0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
34ae0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34af0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
34b00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34b10 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
34b20 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
34b30 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
34b40 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
34b50 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
34b60 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
34b70 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
34b80 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
34b90 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
34ba0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
34bb0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
34bc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
34bd0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
34be0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
34bf0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
34c00 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
34c10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34c20 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
34c30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34c40 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
34c50 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
34c60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34c70 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
34c80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
34c90 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
34ca0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
34cb0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
34cc0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
34cd0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
34ce0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
34cf0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
34d00 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
34d10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
34d20 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
34d30 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
34d40 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
34d50 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
34d60 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
34d70 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34d80 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
34d90 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
34da0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
34db0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
34dc0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
34dd0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
34de0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
34df0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
34e00 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
34e10 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
34e20 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
34e30 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34e40 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
34e50 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
34e60 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
34e70 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
34e80 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
34e90 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
34ea0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
34eb0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
34ec0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34ed0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
34ee0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
34ef0 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
34f00 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
34f10 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
34f20 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
34f30 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
34f40 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
34f50 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
34f60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34f70 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
34f80 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
34f90 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
34fa0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
34fb0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34fc0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
34fd0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
34fe0 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
34ff0 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
35000 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35010 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
35020 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
35030 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
35040 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
35050 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
35060 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
35070 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
35080 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
35090 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
350a0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
350b0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
350c0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
350d0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
350e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
350f0 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
35100 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
35110 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
35120 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
35130 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
35140 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
35150 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
35160 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
35170 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
35180 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
35190 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
351a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
351b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
351c0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
351d0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
351e0 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
351f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35200 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
35210 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
35220 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
35230 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
35240 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
35250 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
35260 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
35270 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
35280 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
35290 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
352a0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
352b0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
352c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
352d0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
352e0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
352f0 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
35300 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
35310 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
35320 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
35330 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
35340 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
35350 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
35360 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
35370 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
35380 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
35390 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
353a0 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
353b0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
353c0 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
353d0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
353e0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
353f0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
35400 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
35410 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
35420 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
35430 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
35440 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
35450 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
35460 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
35470 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
35480 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
35490 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
354a0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
354b0 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
354c0 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
354d0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
354e0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
354f0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
35500 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
35510 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
35520 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35530 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
35540 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
35550 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
35560 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
35570 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
35580 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
35590 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
355a0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
355b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
355c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
355d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
355e0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
355f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35600 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
35610 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
35620 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
35630 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
35640 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
35650 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
35660 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
35670 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
35680 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
35690 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
356a0 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
356b0 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
356c0 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
356d0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
356e0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
356f0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
35700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35710 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
35720 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
35730 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
35740 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
35750 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
35760 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
35770 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35780 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
35790 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
357a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
357b0 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
357c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
357d0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
357e0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
357f0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
35800 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
35810 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
35820 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
35830 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35840 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
35850 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
35860 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
35870 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
35880 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
35890 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
358a0 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
358b0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
358c0 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
358d0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
358e0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
358f0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
35900 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
35910 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
35920 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
35930 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
35940 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
35950 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
35960 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
35970 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
35980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35990 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
359a0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
359b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
359c0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
359d0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
359e0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
359f0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
35a00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
35a10 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
35a20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
35a30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35a40 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35a50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35a60 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
35a70 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
35a80 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
35a90 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
35aa0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
35ab0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
35ac0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
35ad0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
35ae0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35af0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
35b00 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
35b10 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
35b20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
35b30 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
35b40 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
35b50 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
35b60 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
35b70 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35b80 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
35b90 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
35ba0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
35bb0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
35bc0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
35bd0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
35be0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
35bf0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
35c00 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
35c10 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
35c20 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
35c30 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
35c40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
35c50 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
35c60 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
35c70 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
35c80 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
35c90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
35ca0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
35cb0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
35cc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
35cd0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
35ce0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
35cf0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
35d00 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
35d10 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
35d20 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
35d30 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
35d40 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
35d50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35d60 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
35d70 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
35d80 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
35d90 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
35da0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
35db0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
35dc0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
35dd0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
35de0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
35df0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
35e00 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
35e10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
35e20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35e30 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
35e40 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
35e50 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
35e60 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
35e70 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
35e80 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
35e90 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
35ea0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
35eb0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
35ec0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35ed0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
35ee0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
35ef0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
35f00 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
35f10 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
35f20 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
35f30 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
35f40 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
35f50 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
35f60 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
35f70 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
35f80 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35f90 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
35fa0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
35fb0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
35fc0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
35fd0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
35fe0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
35ff0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
36000 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
36010 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
36020 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36030 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
36040 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
36050 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
36060 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36070 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
36080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
36090 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
360a0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
360b0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
360c0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
360d0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
360e0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
360f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
36100 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
36110 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
36120 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
36130 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
36140 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
36150 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
36160 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
36170 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
36180 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
36190 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
361a0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
361b0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
361c0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
361d0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
361e0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
361f0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
36200 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
36210 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
36220 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
36230 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
36240 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
36250 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
36260 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
36270 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
36280 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
36290 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
362a0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
362b0 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  key */.);.int sq
362c0 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20  lite3_key_v2(.  
362d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
362e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
362f0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36300 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36310 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36320 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
36330 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
36340 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
36350 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
36360 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
36370 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
36380 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
36390 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
363a0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
363b0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
363c0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
363d0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
363e0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
363f0 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
36400 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
36410 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
36420 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
36430 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
36440 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
36450 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
36460 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
36470 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
36480 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36490 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
364a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
364b0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
364c0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
364d0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
364e0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
364f0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
36500 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73   key */.);.int s
36510 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28  qlite3_rekey_v2(
36520 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36540 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36550 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36560 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
36570 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
36580 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
36590 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
365a0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
365b0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
365c0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
365d0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
365e0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
365f0 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
36600 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
36610 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
36620 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
36630 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
36640 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
36650 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
36660 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
36670 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
36680 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
36690 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
366a0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
366b0 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
366c0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
366d0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
366e0 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
366f0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
36700 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
36710 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
36720 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
36730 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
36740 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
36750 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
36760 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
36770 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
36780 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
36790 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
367a0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
367b0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
367c0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
367d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
367e0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
367f0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
36800 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
36810 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
36820 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
36830 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
36840 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
36850 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
36860 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
36870 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
36880 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
36890 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
368a0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
368b0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
368c0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
368d0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
368e0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
368f0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
36900 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
36910 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
36920 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
36930 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
36940 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
36950 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
36960 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
36970 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
36980 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
36990 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
369a0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
369b0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
369c0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
369d0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
369e0 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
369f0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
36a00 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36a10 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
36a20 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
36a30 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
36a40 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
36a50 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
36a60 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
36a70 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
36a80 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
36a90 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
36aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
36ab0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
36ac0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
36ad0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
36ae0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
36af0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
36b00 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
36b10 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
36b20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
36b30 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
36b40 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
36b50 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
36b60 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
36b70 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
36b80 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
36b90 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
36ba0 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
36bb0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
36bc0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
36bd0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
36be0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
36bf0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
36c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36c10 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
36c20 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
36c30 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
36c40 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
36c50 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
36c60 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
36c70 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
36c80 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
36c90 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
36ca0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
36cb0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
36cc0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36cd0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36ce0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
36cf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36d00 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
36d10 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
36d20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
36d30 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
36d40 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
36d50 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36d60 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
36d70 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
36d80 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
36d90 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
36da0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
36db0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36dc0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36dd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
36de0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
36df0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
36e00 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
36e10 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36e20 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36e30 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
36e40 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
36e50 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
36e60 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
36e70 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36e80 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
36e90 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
36ea0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36eb0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36ec0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
36ed0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
36ee0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
36ef0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
36f00 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
36f10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
36f30 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
36f40 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
36f50 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
36f60 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
36f70 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
36f80 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
36f90 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
36fa0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
36fb0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
36fc0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
36fd0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
36fe0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
36ff0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
37000 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
37010 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
37020 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
37030 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37040 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
37050 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
37060 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
37070 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
37080 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
37090 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
370a0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
370b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
370c0 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69  3_open] or [sqli
370d0 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f  te3_open_v2].  O
370e0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
370f0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
37100 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
37110 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
37120 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20  files may fail. 
37130 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65   Here is an.** e
37140 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f  xample of how to
37150 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43   do this using C
37160 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64  ++ with the Wind
37170 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a  ows Runtime:.**.
37180 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
37190 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20  pre>.** LPCWSTR 
371a0 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a  zPath = Windows:
371b0 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63  :Storage::Applic
371c0 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65  ationData::Curre
371d0 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  nt->.** &nbsp;  
371e0 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64     TemporaryFold
371f0 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29  er->Path->Data()
37200 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42  ;.** char zPathB
37210 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20  uf&#91;MAX_PATH 
37220 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d  + 1&#93;;.** mem
37230 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c  set(zPathBuf, 0,
37240 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66   sizeof(zPathBuf
37250 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54  ));.** WideCharT
37260 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54  oMultiByte(CP_UT
37270 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31  F8, 0, zPath, -1
37280 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65  , zPathBuf, size
37290 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a  of(zPathBuf),.**
372a0 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c   &nbsp;     NULL
372b0 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69  , NULL);.** sqli
372c0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
372d0 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  ry = sqlite3_mpr
372e0 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68  intf("%s", zPath
372f0 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  Buf);.** </pre><
37300 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a  /blockquote>.*/.
37310 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
37320 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
37330 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
37340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
37350 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
37360 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65  Holding Database
37370 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
37380 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
37390 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
373a0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
373b0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
373c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
373d0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
373e0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
373f0 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
37400 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77 69  .** specified wi
37410 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
37420 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74  thname and creat
37430 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20 62  ed or accessed b
37440 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e  y.** SQLite when
37450 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
37460 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74  n windows [sqlit
37470 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69  e3_vfs | VFS] wi
37480 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a  ll be assumed.**
37490 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20   to be relative 
374a0 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  to that director
374b0 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61  y.)^ ^If this va
374c0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
374d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  .** pointer, the
374e0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
374f0 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61   that all databa
37500 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66 69  se files specifi
37510 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c  ed.** with a rel
37520 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
37530 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74  re relative to t
37540 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
37550 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tory.** for the 
37560 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74  process.  Only t
37570 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d  he windows VFS m
37580 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69 73  akes use of this
37590 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61   global.** varia
375a0 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72  ble; it is ignor
375b0 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20 56  ed by the unix V
375c0 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69  FS..**.** Changi
375d0 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ng the value of 
375e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77 68  this variable wh
375f0 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20 63  ile a database c
37600 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  onnection is.** 
37610 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20  open can result 
37620 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61 74  in a corrupt dat
37630 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  abase..**.** It 
37640 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37650 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37660 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
37670 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
37680 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
37690 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
376a0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
376b0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
376c0 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
376d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
376e0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
376f0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
37700 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
37710 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
37720 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
37730 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
37740 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
37750 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
37760 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
37770 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
37780 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
37790 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
377a0 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
377b0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
377c0 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
377d0 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
377e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61  ..**.** ^The [da
377f0 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  ta_store_directo
37800 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
37810 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37820 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
37830 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
37840 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37850 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
37860 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
37870 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61  more,.** the [da
37880 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  ta_store_directo
37890 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
378a0 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
378b0 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
378c0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
378d0 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
378e0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
378f0 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
37900 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
37910 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
37920 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
37930 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
37940 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37950 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
37960 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
37970 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
37980 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
37990 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
379a0 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
379b0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
379c0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
379d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
379e0 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
379f0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
37a00 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  ta_store_directo
37a10 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
37a20 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
37a30 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
37a40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74  har *sqlite3_dat
37a50 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  a_directory;../*
37a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
37a70 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
37a80 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
37a90 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
37aa0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
37ab0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
37ac0 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
37ad0 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
37ae0 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
37af0 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
37b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37b10 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
37b20 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
37b30 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
37b40 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
37b50 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
37b60 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
37b70 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
37b80 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
37b90 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
37ba0 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
37bb0 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
37bc0 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
37bd0 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
37be0 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
37bf0 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
37c00 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
37c10 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
37c20 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
37c30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
37c40 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
37c50 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
37c60 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
37c70 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
37c80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
37c90 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
37ca0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
37cb0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
37cc0 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
37cd0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
37ce0 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
37cf0 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
37d00 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
37d10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
37d20 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
37d30 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
37d40 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
37d50 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
37d60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
37d70 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
37d80 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
37d90 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
37da0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37db0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
37dc0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
37dd0 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
37de0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37df0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
37e00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
37e10 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
37e20 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
37e30 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
37e40 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
37e50 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
37e60 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
37e70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
37e80 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
37e90 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
37ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37eb0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
37ec0 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
37ed0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
37ee0 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
37ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37f00 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
37f10 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
37f20 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
37f30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37f40 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
37f50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37f60 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
37f70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
37f80 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
37f90 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
37fa0 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
37fb0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
37fc0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
37fd0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
37fe0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
37ff0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
38000 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
38010 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
38020 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20  he Filename For 
38030 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
38040 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
38050 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65   sqlite3_db_file
38060 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66  name(D,N) interf
38070 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
38080 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e  inter to a filen
38090 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ame.** associate
380a0 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20  d with database 
380b0 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  N of connection 
380c0 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61  D.  ^The main da
380d0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68  tabase file.** h
380e0 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  as the name "mai
380f0 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  n".  If there is
38100 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74   no attached dat
38110 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64  abase N on the d
38120 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
38130 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64  ction D, or if d
38140 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74  atabase N is a t
38150 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d  emporary or in-m
38160 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20  emory database, 
38170 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  then.** a NULL p
38180 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
38190 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
381a0 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64  ilename returned
381b0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
381c0 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20  n is the output 
381d0 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50  of the.** xFullP
381e0 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f  athname method o
381f0 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49  f the [VFS].  ^I
38200 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
38210 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
38220 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75  ill be an absolu
38230 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65  te pathname, eve
38240 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  n if the filenam
38250 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65  e used.** to ope
38260 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  n the database o
38270 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20  riginally was a 
38280 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20  URI or relative 
38290 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e  pathname..*/.con
382a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
382b0 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c  _db_filename(sql
382c0 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
382d0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
382e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
382f0 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20   Determine if a 
38300 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61 64  database is read
38310 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  -only.**.** ^The
38320 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64   sqlite3_db_read
38330 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66  only(D,N) interf
38340 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66  ace returns 1 if
38350 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a   the database N.
38360 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e  ** of connection
38370 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c   D is read-only,
38380 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61 64   0 if it is read
38390 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66  /write, or -1 if
383a0 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65   N is not.** the
383b0 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62   name of a datab
383c0 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f  ase on connectio
383d0 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  n D..*/.int sqli
383e0 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
383f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
38400 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
38410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38420 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
38430 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
38440 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
38450 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38460 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
38470 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
38480 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
38490 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
384a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
384b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
384c0 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
384d0 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
384e0 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
384f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
38500 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
38510 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
38520 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
38530 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
38540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38550 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
38560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38570 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
38580 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
38590 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
385a0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
385b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
385c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
385d0 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
385e0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
385f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
38600 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
38610 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
38620 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
38630 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
38640 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
38650 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
38660 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
38670 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
38680 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
38690 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
386a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
386b0 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
386c0 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
386d0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
386e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
386f0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
38700 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
38710 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
38720 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
38730 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
38740 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
38750 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
38760 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
38770 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
38780 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
38790 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
387a0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
387b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
387c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
387d0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
387e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
387f0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29