/ Hex Artifact Content
Login

Artifact 8f46bc8c0d2f08abd9965ebcd0aaef5607ffa27f:


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 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5220: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5230: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5240: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5250: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5260: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5270: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5280: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5290: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
52a0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
52b0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
52c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
52d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
52e0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
52f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5300: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5310: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5320: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5330: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5360: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5370: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5380: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
53b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
53c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5400: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5410: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5440: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5450: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5470: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5480: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5490: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
54d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
54e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
54f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5500: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5510: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5520: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5550: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5560: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5590: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
55a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
55d0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
55e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5600: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5610: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5620: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5640: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5650: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5660: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5680: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5690: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
56a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56c0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
56d0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
56e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
56f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5720: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5730: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5740: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5760: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5770: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5780: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5790: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57b0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
57c0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
57d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5810: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5820: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5830: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5860: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5870: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5880: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5890: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
58a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
58b0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
58c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
58d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
58e0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
58f0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5900: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5910: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5920: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5930: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5940: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5950: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5960: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5970: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5980: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5990: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
59a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
59b0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
59c0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
59d0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
59e0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
59f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5a00: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5a10: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5a20: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5a30: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5a40: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5a50: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5a60: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5a70: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5a80: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5a90: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5ab0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5ac0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5ad0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5ae0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5af0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5b00: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5b10: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5b20: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5b30: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5b40: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5b50: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5b60: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b70: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5b80: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5b90: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5ba0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5bb0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5bc0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5bd0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
5be0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
5bf0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
5c00: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
5c10: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
5c20: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
5c30: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
5c40: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
5c50: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
5c60: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
5c70: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
5c80: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
5c90: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
5ca0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
5cb0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
5cc0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
5cd0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
5ce0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
5cf0: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
5d00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d10: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
5d20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d30: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
5d40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d50: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
5d60: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5d70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5d80: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5da0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
5db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
5dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5dd0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5de0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5df0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
5e00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e40: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5e50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5e60: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
5e70: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e90: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
5ea0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5eb0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
5ec0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ed0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
5ee0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5f00: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
5f10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5f20: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
5f30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5f40: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
5f50: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
5f60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f70: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
5f80: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
5f90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5fa0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
5fb0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
5fc0: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
5fd0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
5fe0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
5ff0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6000: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6010: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6020: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6030: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6040: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6050: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6060: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6070: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6080: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6090: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
60a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
60b0: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
60c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
60d0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
60e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
60f0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6100: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6110: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6120: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6130: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6140: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6150: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6160: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6170: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6180: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6190: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
61a0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
61b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
61c0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
61d0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
61e0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
61f0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6200: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6210: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6230: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6240: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6250: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6260: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6270: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6280: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6290: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
62a0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
62b0: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
62c0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
62d0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
62e0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
62f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6300: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6310: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6320: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6330: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6340: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6350: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6360: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6370: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6380: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6390: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
63a0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
63b0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
63c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
63d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
63e0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
63f0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6400: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6410: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6420: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6430: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6440: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6450: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6460: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6470: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6480: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6490: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
64a0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
64b0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
64c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
64d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
64e0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
64f0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6500: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6510: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6520: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6530: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6540: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6550: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6560: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6570: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6580: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6590: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
65a0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
65b0: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
65c0: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
65d0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
65e0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
65f0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6600: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6610: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6620: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6630: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6640: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6650: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6670: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
6680: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6690: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
66a0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
66b0: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
66c0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
66d0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
66e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
66f0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6700: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
6710: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6720: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6730: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6740: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
6750: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
6760: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
6770: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
6780: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
6790: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
67a0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
67b0: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
67c0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
67d0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
67e0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
67f0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
6800: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
6810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6830: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6840: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
6850: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
6860: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
6870: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
6880: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
6890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
68a0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
68b0: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
68c0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
68d0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
68e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
68f0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
6900: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
6910: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
6920: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6930: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
6940: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
6950: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
6960: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
6970: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6980: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
6990: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
69a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
69b0: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
69c0: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
69d0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
69f0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6a00: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6a10: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
6a20: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
6a30: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
6a40: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
6a50: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
6a60: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
6a70: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
6a80: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
6a90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6aa0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
6ab0: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
6ac0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
6ad0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
6ae0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6af0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
6b00: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
6b10: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
6b20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6b30: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
6b40: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
6b50: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
6b60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6b70: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
6b80: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
6b90: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
6ba0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
6bb0: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
6bc0: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
6bd0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
6be0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
6bf0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6c00: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
6c10: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6c20: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
6c30: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
6c40: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6c50: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6c60: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6c70: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6c80: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6c90: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6ca0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6cb0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6cc0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6cd0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6ce0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6cf0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
6d00: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
6d10: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
6d20: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
6d30: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
6d40: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
6d50: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6d60: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6d70: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6d80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6d90: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6da0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6db0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6dc0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6dd0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6de0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6df0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6e10: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6e30: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6e40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6e50: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6e60: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6e70: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6e80: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6e90: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6ea0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6eb0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6ec0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6ed0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6ee0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6ef0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6f00: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6f10: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6f20: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6f30: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6f40: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6f50: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6f60: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6f70: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6f80: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6f90: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6fa0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6fb0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6fc0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6fd0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6fe0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6ff0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7000: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7010: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7020: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7040: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7050: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7060: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7070: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7080: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7090: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
70a0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
70b0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
70c0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
70d0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
70e0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
70f0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7100: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7110: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7120: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7130: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7140: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7150: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7160: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7170: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7180: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7190: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
71a0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
71b0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
71c0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
71d0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
71e0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
71f0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7200: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7210: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7220: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7230: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7240: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7250: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7260: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7270: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7280: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7290: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
72a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
72b0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
72c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
72d0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
72e0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
72f0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7300: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7310: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7320: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7330: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7340: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7350: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7360: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7370: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7380: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7390: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
73a0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
73c0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
73d0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
73e0: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
73f0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7400: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7410: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7420: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7430: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7440: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7450: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7460: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7470: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7480: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7490: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
74a0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
74b0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
74c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
74d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74e0: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
74f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7500: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7510: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7520: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7530: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7540: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7550: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7560: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7570: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7580: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7590: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
75a0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
75b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75c0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
75d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
75e0: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
75f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7600: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7610: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7620: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7630: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7640: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7650: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7660: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7670: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7680: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7690: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
76a0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
76b0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
76c0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
76d0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
76e0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
76f0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7700: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7710: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7720: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7730: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7740: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7750: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7760: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7770: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7780: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7790: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
77a0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
77b0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
77c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
77d0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
77e0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
77f0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7800: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7810: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7820: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7830: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7840: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7850: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7860: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7870: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7880: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7890: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
78a0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
78b0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
78c0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
78d0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
78e0: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
78f0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7900: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7910: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7920: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7930: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7940: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7950: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7960: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7970: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7980: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7990: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
79a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
79b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
79c0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
79d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
79e0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
79f0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7a00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7a10: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
7a20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
7a30: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7a40: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7a50: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7a60: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7a70: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7a80: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7a90: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7aa0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7ab0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7ac0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7ad0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7ae0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7af0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
7b00: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
7b10: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7b20: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7b30: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
7b40: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
7b50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7b60: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7b80: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
7b90: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
7ba0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7bb0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
7bc0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
7bd0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7be0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7bf0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
7c00: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
7c10: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7c20: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
7c30: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
7c40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7c50: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c60: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c70: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
7c80: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
7c90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7ca0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
7cb0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
7cc0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
7cd0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7ce0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7cf0: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
7d00: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
7d10: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
7d20: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7d30: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
7d40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7d50: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7d60: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7d70: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7d80: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7d90: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7da0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7db0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7dc0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7dd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7de0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7df0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7e00: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7e10: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7e20: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7e30: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7e40: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7e50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7e60: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7e70: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7e80: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7e90: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7ea0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7eb0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7ec0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7ed0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7ee0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7ef0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7f00: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7f10: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7f20: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7f30: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7f40: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7f50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7f60: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7f70: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7f80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7f90: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7fa0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7fb0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7fc0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7fd0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7fe0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7ff0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8000: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8010: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8020: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8030: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8040: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8060: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8070: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8080: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8090: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
80a0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
80b0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
80c0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
80d0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
80e0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
80f0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8100: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8110: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8120: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8130: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8140: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8150: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8160: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8170: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8180: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8190: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
81a0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
81b0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
81c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
81d0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
81e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
81f0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8200: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8210: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8220: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8230: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8240: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8250: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8260: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8270: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8280: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8290: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
82a0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
82b0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
82c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
82d0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
82e0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
82f0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8300: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8310: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8320: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8330: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8340: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8350: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8360: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8370: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8380: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8390: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
83a0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
83b0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
83c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
83d0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
83e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
83f0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
8400: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8410: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8420: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8430: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8440: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8450: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8460: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8470: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8480: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8490: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
84a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
84b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
84c0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
84d0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
84e0: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
84f0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8500: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8510: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8520: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8530: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8550: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8560: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8570: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8580: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8590: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
85a0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
85b0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
85c0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
85d0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
85e0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
85f0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8600: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8610: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8620: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8630: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8640: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8650: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8660: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8670: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8680: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8690: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
86a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
86b0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
86c0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
86d0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
86e0: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
86f0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  re it.  .**.** ^
8700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8710: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
8720: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8730: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
8740: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
8750: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
8760: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
8770: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
8780: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
8790: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
87a0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
87b0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
87c0: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
87d0: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
87e0: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
87f0: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
8800: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
8810: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
8820: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
8830: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
8840: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
8850: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
8860: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
8870: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
8880: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
8890: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
88a0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
88b0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
88c0: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
88d0: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
88e0: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
88f0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
8900: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
8910: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
8920: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
8930: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
8940: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
8950: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
8960: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
8970: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
8980: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
8990: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
89a0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
89b0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
89c0: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
89d0: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
89e0: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
89f0: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
8a00: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
8a10: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
8a20: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
8a30: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
8a40: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
8a50: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
8a60: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
8a70: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
8a80: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
8a90: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
8aa0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
8ab0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
8ac0: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
8ad0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
8ae0: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
8af0: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
8b00: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
8b10: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
8b20: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
8b30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
8b40: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
8b50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8b60: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8b70: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
8b80: 20 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c   | Write AHead L
8b90: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
8ba0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
8bb0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
8bc0: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
8bd0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8be0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
8bf0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
8c00: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
8c10: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
8c20: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
8c30: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
8c40: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
8c50: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
8c60: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8c70: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
8c80: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
8c90: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
8ca0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
8cb0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
8cc0: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
8cd0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
8ce0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
8cf0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
8d00: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
8d10: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8d20: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
8d30: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
8d40: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
8d50: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
8d60: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
8d70: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
8d80: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
8d90: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
8da0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
8db0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8dc0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8dd0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
8de0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
8df0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
8e00: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
8e10: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
8e20: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
8e30: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8e40: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
8e50: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
8e60: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
8e70: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
8e80: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
8e90: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
8ea0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
8eb0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
8ec0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
8ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
8ee0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
8ef0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8f00: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
8f10: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
8f20: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
8f30: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
8f40: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
8f50: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
8f60: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
8f70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
8f80: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
8f90: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
8fa0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8fb0: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
8fc0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
8fd0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
8fe0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8ff0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
9000: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
9010: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
9020: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
9030: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
9040: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
9050: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
9060: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
9070: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
9080: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
9090: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
90a0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
90b0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
90c0: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
90d0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tting..**.** ^Th
90e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
90f0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9100: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
9110: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
9120: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
9130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
9140: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
9150: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
9160: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
9170: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
9180: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
9190: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
91a0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
91b0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
91c0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
91d0: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
91e0: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
91f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9200: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
9210: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
9220: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
9230: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
9240: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
9250: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
9260: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
9270: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
9280: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
9290: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
92a0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
92b0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
92c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
92d0: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
92e0: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
92f0: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
9300: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
9310: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9320: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
9330: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
9340: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
9350: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
9360: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
9370: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
9380: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
9390: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
93a0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
93b0: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
93c0: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
93d0: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
93e0: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
93f0: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
9400: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
9410: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
9420: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
9430: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
9440: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
9450: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
9460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9470: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
9480: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
9490: 73 65 20 6f 6e 6c 79 2e 0a 2a 2f 0a 23 64 65 66  se only..*/.#def
94a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
94b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
94c0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
94d0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
94e0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
94f0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
9500: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
9510: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
9520: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
9530: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
9540: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
9550: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
9560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9570: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
9580: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
9590: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
95a0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
95b0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
95c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
95d0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
95e0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
95f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9600: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
9610: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
9620: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9630: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
9640: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
9650: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9660: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
9670: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9680: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
96a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
96b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
96c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
96d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
96e0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
96f0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 0a  VERWRITE    13..
9700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9710: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
9720: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
9730: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
9740: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
9750: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
9760: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
9770: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
9780: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
9790: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
97a0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
97b0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
97c0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
97d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
97e0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
97f0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
9800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
9810: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
9820: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
9830: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
9840: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
9850: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
9860: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9870: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
9880: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
9890: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
98a0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
98b0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
98c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
98d0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
98e0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
98f0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
9900: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
9910: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
9920: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
9930: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
9940: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
9950: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
9960: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
9970: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
9980: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
9990: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
99a0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
99b0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
99c0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
99d0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
99e0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
99f0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
9a00: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
9a10: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
9a20: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
9a30: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9a40: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
9a50: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
9a60: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
9a70: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
9a80: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
9a90: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
9aa0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
9ab0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
9ac0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
9ad0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
9ae0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
9af0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
9b00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
9b10: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
9b20: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
9b30: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
9b40: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
9b50: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
9b60: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
9b70: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
9b80: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
9b90: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
9ba0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
9bb0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
9bc0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
9bd0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
9be0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
9bf0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
9c00: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
9c10: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
9c20: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
9c30: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
9c40: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
9c50: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
9c60: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
9c70: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
9c80: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
9c90: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
9ca0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
9cb0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
9cc0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
9cd0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
9ce0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
9cf0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
9d00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9d10: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
9d20: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
9d30: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
9d40: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
9d50: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
9d60: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
9d70: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
9d80: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
9d90: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
9da0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
9db0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
9dc0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
9dd0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
9de0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
9df0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
9e00: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
9e10: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
9e20: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
9e30: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
9e40: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
9e50: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
9e60: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
9e70: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
9e80: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
9e90: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
9ea0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
9eb0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
9ec0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
9ed0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
9ee0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
9ef0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
9f00: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
9f10: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
9f20: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
9f30: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
9f40: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
9f50: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
9f60: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
9f70: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
9f80: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
9f90: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
9fa0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
9fb0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
9fc0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
9fd0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
9fe0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
9ff0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
a000: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
a010: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
a020: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
a030: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
a040: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
a050: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
a060: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
a070: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
a080: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
a090: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
a0a0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
a0b0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
a0c0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
a0d0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
a0e0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
a0f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
a100: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
a110: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
a120: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
a130: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
a140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
a150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
a160: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
a170: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
a180: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
a190: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
a1a0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
a1b0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
a1c0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
a1d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
a1e0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
a1f0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
a200: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
a210: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
a220: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
a230: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
a240: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
a250: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
a260: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
a270: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
a280: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
a290: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
a2a0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
a2b0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
a2c0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
a2d0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
a2e0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
a2f0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
a300: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
a310: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
a320: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
a330: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
a340: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
a350: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
a360: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
a370: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
a380: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
a390: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
a3a0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
a3b0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
a3c0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
a3d0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
a3e0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
a3f0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
a400: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
a410: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
a420: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
a430: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
a440: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
a450: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
a460: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a470: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
a480: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
a490: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
a4a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
a4b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
a4c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
a4d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
a4e0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
a4f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
a500: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
a510: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
a520: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
a530: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
a540: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
a550: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
a560: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
a570: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
a580: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
a590: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
a5a0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
a5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
a5c0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
a5d0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
a5e0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
a5f0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
a600: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
a610: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
a620: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
a630: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
a640: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
a650: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
a660: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
a670: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
a680: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
a690: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
a6a0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
a6b0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
a6c0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
a6d0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
a6e0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
a6f0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
a700: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
a710: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
a720: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
a730: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
a740: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
a750: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
a760: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
a770: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
a780: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
a790: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
a7a0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
a7b0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
a7c0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a7d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
a7e0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
a7f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
a800: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
a810: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
a820: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
a830: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
a840: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
a850: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
a860: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
a870: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
a880: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
a890: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
a8a0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
a8b0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
a8c0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
a8d0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
a8e0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
a8f0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
a900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
a910: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
a920: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
a930: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
a940: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
a950: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
a960: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
a970: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
a980: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
a990: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
a9a0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
a9b0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
a9c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
a9d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
a9e0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
a9f0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
aa00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
aa10: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
aa20: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
aa30: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
aa40: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
aa50: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
aa60: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
aa70: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
aa80: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
aa90: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
aaa0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
aab0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
aac0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
aad0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
aae0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
aaf0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
ab00: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
ab10: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
ab20: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
ab30: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
ab40: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
ab50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
ab60: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
ab70: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
ab80: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
ab90: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
aba0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
abb0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
abc0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
abd0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
abe0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
abf0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ac00: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
ac10: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
ac20: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
ac30: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
ac40: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
ac50: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
ac60: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
ac70: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
ac80: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
ac90: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
aca0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
acb0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
acc0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
acd0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
ace0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
acf0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
ad00: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
ad10: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
ad20: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
ad30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
ad40: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
ad50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ad60: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
ad70: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
ad80: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
ad90: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ada0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
adb0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
adc0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
add0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
ade0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
adf0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
ae00: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
ae10: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
ae20: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
ae30: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
ae40: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
ae50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
ae60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
ae70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
ae80: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
ae90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
aea0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
aeb0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
aec0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
aed0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
aee0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
aef0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
af00: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
af10: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
af20: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
af30: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
af40: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
af50: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
af60: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
af70: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
af80: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
af90: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
afa0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
afb0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
afc0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
afd0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
afe0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
aff0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
b000: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
b010: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
b020: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
b030: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
b040: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
b050: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
b060: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
b070: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
b080: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
b090: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
b0a0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
b0b0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
b0c0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
b0d0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
b0e0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
b0f0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
b100: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
b110: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
b120: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
b130: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
b140: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
b150: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
b160: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
b170: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
b180: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
b190: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
b1a0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
b1b0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
b1c0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
b1d0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
b1e0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
b1f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
b200: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
b210: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
b220: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
b230: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
b240: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
b250: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
b260: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
b270: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
b280: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
b290: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
b2a0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
b2b0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
b2c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
b2d0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
b2e0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
b2f0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
b300: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
b310: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
b320: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
b330: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
b340: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
b350: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
b360: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
b370: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
b380: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
b390: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
b3a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
b3b0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
b3c0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
b3d0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
b3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
b3f0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
b400: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
b410: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
b420: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
b430: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
b440: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
b450: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
b460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
b470: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
b480: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
b490: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
b4a0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
b4b0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
b4c0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
b4d0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
b4e0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
b4f0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
b500: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
b510: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
b520: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
b530: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
b540: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
b550: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
b560: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
b570: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
b580: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
b590: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
b5a0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
b5b0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
b5c0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
b5d0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
b5e0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
b5f0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
b600: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
b610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
b620: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
b630: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
b640: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
b650: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
b660: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
b670: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
b680: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
b690: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
b6a0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
b6b0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
b6c0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
b6d0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
b6e0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
b6f0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
b700: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
b710: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
b720: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
b730: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
b740: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
b750: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
b760: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
b770: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
b780: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
b790: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
b7a0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
b7b0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
b7c0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
b7d0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
b7e0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
b7f0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
b800: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
b810: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
b820: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
b830: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
b840: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
b850: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
b860: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
b870: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
b880: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
b890: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
b8a0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
b8b0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
b8c0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
b8d0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
b8e0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
b8f0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
b900: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
b910: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
b920: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
b930: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
b940: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
b950: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
b960: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
b970: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
b980: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
b990: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
b9a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b9b0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
b9c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
b9d0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
b9e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b9f0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
ba00: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
ba10: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
ba20: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
ba30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ba40: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
ba50: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
ba60: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
ba70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ba80: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
ba90: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
baa0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
bab0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
bac0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
bad0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
bae0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
baf0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
bb00: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
bb10: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
bb20: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
bb30: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
bb40: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
bb50: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
bb60: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
bb70: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
bb80: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
bb90: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
bba0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
bbb0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
bbc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
bbd0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
bbe0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
bbf0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
bc00: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
bc10: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
bc20: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
bc30: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
bc40: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
bc50: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
bc60: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
bc70: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
bc80: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
bc90: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
bca0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
bcb0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
bcc0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
bcd0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
bce0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
bcf0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
bd00: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
bd10: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
bd20: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
bd30: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
bd40: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
bd50: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
bd60: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
bd70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
bd80: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
bd90: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
bda0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
bdb0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
bdc0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
bdd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
bde0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
bdf0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
be00: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
be10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
be20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
be30: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
be40: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
be50: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
be60: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
be70: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
be80: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
be90: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
bea0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
beb0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
bec0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
bed0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
bee0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
bef0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
bf00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
bf10: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
bf20: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
bf30: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
bf40: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
bf50: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
bf60: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
bf70: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
bf80: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
bf90: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
bfa0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
bfb0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
bfc0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
bfd0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
bfe0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
bff0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
c000: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
c010: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
c020: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
c030: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
c040: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
c050: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
c060: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
c070: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
c080: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
c090: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
c0a0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
c0b0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
c0c0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
c0d0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
c0e0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
c0f0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
c100: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
c110: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
c120: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
c130: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
c140: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
c150: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
c160: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
c170: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
c180: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
c190: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
c1a0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
c1b0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
c1c0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
c1d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
c1e0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
c1f0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
c200: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
c210: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
c220: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
c230: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
c240: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
c250: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
c260: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
c270: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
c280: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
c290: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
c2a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
c2b0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
c2c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c2d0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
c2e0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
c2f0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
c300: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
c310: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c320: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
c330: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
c340: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
c350: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
c360: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
c370: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
c380: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
c390: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
c3a0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
c3b0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
c3c0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
c3d0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
c3e0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
c3f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
c400: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
c410: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
c420: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
c430: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
c440: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
c450: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
c460: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
c470: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
c480: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
c490: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
c4a0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
c4b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
c4c0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
c4d0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
c4e0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
c4f0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
c500: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
c510: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
c520: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
c530: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
c540: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
c550: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
c560: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
c570: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
c580: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
c590: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
c5a0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
c5b0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
c5c0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
c5d0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
c5e0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
c5f0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
c600: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
c610: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
c620: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
c630: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
c640: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
c650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
c660: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
c670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c680: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
c690: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c6a0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
c6b0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
c6c0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
c6d0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
c6e0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
c6f0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
c700: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
c710: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
c720: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
c730: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
c740: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
c750: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
c760: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
c770: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
c780: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
c790: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
c7a0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
c7b0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
c7c0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
c7d0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
c7e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
c7f0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
c800: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
c810: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
c820: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
c830: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
c840: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
c850: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
c860: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
c870: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
c880: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
c890: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
c8a0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
c8b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
c8c0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
c8d0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
c8e0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
c8f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c900: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
c910: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
c920: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
c930: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
c940: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
c950: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
c960: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
c970: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
c980: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
c990: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c9a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
c9b0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
c9c0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
c9d0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
c9e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c9f0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
ca00: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
ca10: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
ca20: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
ca30: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
ca40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ca50: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
ca60: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
ca70: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ca80: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
ca90: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
caa0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
cab0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cac0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
cad0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
cae0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
caf0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
cb00: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
cb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
cb20: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
cb30: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
cb40: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
cb50: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
cb60: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
cb70: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
cb80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cb90: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
cba0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
cbb0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
cbc0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
cbd0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
cbe0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
cbf0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
cc00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cc10: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
cc20: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
cc30: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
cc40: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
cc50: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
cc60: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
cc70: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
cc80: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
cc90: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
cca0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
ccb0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
ccc0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
ccd0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
cce0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ccf0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
cd00: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
cd10: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
cd20: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
cd30: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
cd40: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
cd50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
cd60: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
cd70: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
cd80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cd90: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
cda0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
cdb0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
cdc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
cdd0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
cde0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
cdf0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
ce00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ce10: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
ce20: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
ce30: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
ce40: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
ce50: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
ce60: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
ce70: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
ce80: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
ce90: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
cea0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
ceb0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
cec0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
ced0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
cee0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
cef0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
cf00: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
cf10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
cf20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
cf30: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
cf40: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
cf50: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
cf60: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
cf70: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
cf80: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
cf90: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
cfa0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
cfb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
cfc0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
cfd0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
cfe0: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
cff0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d000: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
d010: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
d020: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
d030: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
d040: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
d050: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
d060: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
d070: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
d080: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
d090: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
d0a0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
d0b0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
d0c0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
d0d0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
d0e0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
d0f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
d100: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
d110: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
d120: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
d130: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
d140: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d150: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
d160: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
d170: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
d180: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
d190: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
d1a0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
d1b0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
d1c0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
d1d0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
d1e0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
d1f0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
d200: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
d210: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d220: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
d230: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
d240: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
d250: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
d260: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
d270: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
d280: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
d290: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
d2a0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
d2b0: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
d2c0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
d2d0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
d2e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
d2f0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
d300: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
d310: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
d320: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
d330: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
d340: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
d350: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d360: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
d370: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
d380: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
d390: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
d3a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
d3b0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
d3c0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
d3d0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
d3e0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
d3f0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
d400: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
d410: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
d420: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
d430: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
d440: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
d450: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
d460: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
d470: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
d480: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
d490: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
d4a0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
d4b0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
d4c0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
d4d0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
d4e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
d4f0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
d500: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
d510: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
d520: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
d530: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
d540: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
d550: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d560: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
d570: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
d580: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
d590: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
d5a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
d5b0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
d5c0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
d5d0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
d5e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
d5f0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
d600: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d610: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
d620: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
d630: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
d640: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
d650: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
d660: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
d670: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
d680: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
d690: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
d6a0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
d6b0: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
d6c0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
d6d0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
d6e0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
d6f0: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
d700: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
d710: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
d720: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
d730: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d740: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
d750: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
d760: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
d770: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
d780: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
d790: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
d7a0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
d7b0: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
d7c0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
d7d0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
d7e0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
d7f0: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
d800: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
d810: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
d820: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
d830: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
d840: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d850: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
d860: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
d870: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d880: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
d890: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
d8a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d8b0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
d8c0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
d8d0: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
d8e0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
d8f0: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
d900: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
d910: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
d920: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
d930: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
d940: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
d950: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
d960: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
d970: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
d980: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
d990: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
d9a0: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
d9b0: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
d9c0: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
d9d0: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
d9e0: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
d9f0: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
da00: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
da10: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
da20: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
da30: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
da40: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
da50: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
da60: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
da70: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
da80: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
da90: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
daa0: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
dab0: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
dac0: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
dad0: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
dae0: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
daf0: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
db00: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
db10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
db20: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
db30: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
db40: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
db50: 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
db60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
db70: 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
db80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
db90: 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
dba0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
dbb0: 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
dbc0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
dbd0: 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
dbe0: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
dbf0: 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
dc00: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
dc10: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
dc20: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
dc30: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
dc40: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
dc50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
dc60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
dc70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
dc80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
dc90: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
dca0: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
dcb0: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
dcc0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
dcd0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
dce0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
dcf0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
dd00: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
dd10: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
dd20: 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
dd30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
dd40: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
dd50: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
dd60: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
dd70: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
dd80: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
dd90: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
dda0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
ddb0: 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
ddc0: 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
ddd0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
dde0: 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
ddf0: 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
de00: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
de10: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
de20: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
de30: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
de40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
de50: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
de60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
de70: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
de80: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
de90: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
dea0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
deb0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
dec0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
ded0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
dee0: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
def0: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
df00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
df10: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
df20: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
df30: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
df40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
df50: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
df60: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
df70: 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
df80: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
df90: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
dfa0: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
dfb0: 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
dfc0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
dfd0: 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
dfe0: 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
dff0: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
e000: 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
e010: 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
e020: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
e030: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
e040: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
e050: 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
e060: 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
e070: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
e080: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
e090: 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
e0a0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
e0b0: 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
e0c0: 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
e0d0: 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
e0e0: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
e0f0: 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e  uccessful..*/.in
e100: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
e110: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
e120: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
e130: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
e140: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
e150: 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
e160: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
e170: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
e180: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
e190: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
e1a0: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
e1b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e1c0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
e1d0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
e1e0: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
e1f0: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
e200: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
e210: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
e220: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
e230: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
e240: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
e250: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e260: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
e270: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e280: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
e290: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
e2a0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
e2b0: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
e2c0: 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
e2d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
e2e0: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
e2f0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
e300: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
e310: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e320: 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
e330: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
e340: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
e350: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
e360: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
e370: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
e380: 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
e390: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
e3a0: 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
e3b0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
e3c0: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
e3d0: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
e3e0: 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
e3f0: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
e400: 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
e410: 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
e420: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
e430: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
e440: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
e450: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
e460: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
e470: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
e480: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
e490: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
e4a0: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
e4b0: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
e4c0: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
e4d0: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
e4e0: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
e4f0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
e500: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
e510: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
e520: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
e530: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e540: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
e550: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
e560: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
e570: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
e580: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
e590: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
e5a0: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
e5b0: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
e5c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
e5d0: 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
e5e0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
e5f0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
e600: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
e610: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
e620: 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
e630: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
e640: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
e650: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e660: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
e670: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
e680: 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
e690: 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
e6a0: 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
e6b0: 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
e6c0: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
e6d0: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
e6e0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
e6f0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
e700: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
e710: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
e720: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
e730: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
e740: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
e750: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
e760: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
e770: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
e780: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
e790: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
e7a0: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
e7b0: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
e7c0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
e7d0: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
e7e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
e7f0: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
e800: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
e810: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
e820: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
e830: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
e840: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
e850: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
e860: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
e870: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
e880: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
e890: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
e8a0: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
e8b0: 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
e8c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
e8d0: 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
e8e0: 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
e8f0: 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
e900: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
e910: 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
e920: 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
e930: 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
e940: 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
e950: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
e960: 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
e970: 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
e980: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
e990: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
e9a0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e9b0: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
e9c0: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
e9d0: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
e9e0: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
e9f0: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
ea00: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
ea10: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
ea20: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
ea30: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
ea40: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
ea50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ea60: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
ea70: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
ea80: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
ea90: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
eaa0: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
eab0: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
eac0: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
ead0: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
eae0: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
eaf0: 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
eb00: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
eb10: 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
eb20: 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
eb30: 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
eb40: 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
eb50: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
eb60: 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
eb70: 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
eb80: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
eb90: 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
eba0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
ebb0: 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
ebc0: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
ebd0: 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
ebe0: 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
ebf0: 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
ec00: 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
ec10: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
ec20: 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
ec30: 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
ec40: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
ec50: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
ec60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ec70: 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
ec80: 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
ec90: 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
eca0: 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
ecb0: 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
ecc0: 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
ecd0: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
ece0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
ecf0: 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
ed00: 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
ed10: 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
ed20: 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
ed30: 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
ed40: 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
ed50: 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
ed60: 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
ed70: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
ed80: 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
ed90: 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
eda0: 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
edb0: 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
edc0: 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
edd0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
ede0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
edf0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
ee00: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
ee10: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
ee20: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
ee30: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
ee40: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
ee50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ee60: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
ee70: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
ee80: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
ee90: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
eea0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
eeb0: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
eec0: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
eed0: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
eee0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
eef0: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
ef00: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
ef10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
ef20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
ef30: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
ef40: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
ef50: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
ef60: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
ef70: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
ef80: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
ef90: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
efa0: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
efb0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
efc0: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
efd0: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
efe0: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
eff0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
f000: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
f010: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
f020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f030: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
f040: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
f050: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
f060: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f070: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f080: 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
f090: 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
f0a0: 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
f0b0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
f0c0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
f0d0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
f0e0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
f0f0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
f100: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
f110: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
f120: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f130: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
f140: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
f150: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
f160: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
f170: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
f180: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
f190: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
f1a0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
f1b0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
f1c0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
f1d0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
f1e0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
f1f0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
f200: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
f210: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
f220: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
f230: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
f240: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
f250: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
f260: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
f270: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
f280: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
f290: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
f2a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
f2b0: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
f2c0: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
f2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
f2e0: 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
f2f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
f300: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
f310: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
f320: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
f330: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
f340: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
f350: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
f360: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
f370: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
f380: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
f390: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
f3a0: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
f3b0: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
f3c0: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
f3d0: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
f3e0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
f3f0: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
f400: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f410: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
f420: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
f430: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
f440: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
f450: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
f460: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
f470: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
f480: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f490: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
f4a0: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
f4b0: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
f4c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
f4d0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
f4e0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
f4f0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
f500: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
f510: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
f520: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
f530: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
f540: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f550: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
f560: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
f570: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
f580: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
f590: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
f5a0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
f5b0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
f5c0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
f5d0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f5e0: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
f5f0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
f600: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
f610: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
f620: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f630: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
f640: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
f650: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
f660: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
f670: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
f680: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
f690: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
f6a0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
f6b0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
f6c0: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
f6d0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
f6e0: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
f6f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
f700: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
f710: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
f720: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
f730: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
f740: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
f750: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
f760: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f770: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
f780: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
f790: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f7a0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
f7b0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f7c0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
f7d0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
f7e0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
f7f0: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
f800: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
f810: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
f820: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
f830: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
f840: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
f850: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
f860: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
f870: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
f880: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
f890: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
f8a0: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
f8b0: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
f8c0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
f8d0: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
f8e0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f8f0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
f900: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
f910: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
f920: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
f930: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
f940: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
f950: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
f960: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
f970: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
f980: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
f990: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
f9a0: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
f9b0: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
f9c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
f9d0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
f9e0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
f9f0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
fa00: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
fa10: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
fa20: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fa30: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
fa40: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
fa50: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
fa60: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
fa70: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
fa80: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
fa90: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
faa0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
fab0: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
fac0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
fad0: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
fae0: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
faf0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
fb00: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
fb10: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
fb20: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
fb30: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
fb40: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
fb50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fb60: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
fb70: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
fb80: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
fb90: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
fba0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
fbb0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
fbc0: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
fbd0: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
fbe0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
fbf0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fc00: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
fc10: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
fc20: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
fc30: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
fc40: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
fc50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fc60: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
fc70: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
fc80: 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
fc90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fca0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
fcb0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
fcc0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
fcd0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
fce0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
fcf0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
fd00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
fd10: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
fd20: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
fd30: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
fd40: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
fd50: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
fd60: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
fd70: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
fd80: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
fd90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fda0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
fdb0: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
fdc0: 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
fdd0: 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
fde0: 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
fdf0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
fe00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
fe10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
fe20: 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
fe30: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
fe40: 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
fe50: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
fe60: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
fe70: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
fe80: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
fe90: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
fea0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
feb0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
fec0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
fed0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
fee0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
fef0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
ff00: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ff10: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
ff20: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
ff30: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
ff40: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
ff50: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
ff60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
ff70: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
ff80: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
ff90: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
ffa0: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
ffb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ffc0: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
ffd0: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
ffe0: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
fff0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
10000 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
10010 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
10020 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
10030 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
10040 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10050 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10060 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
10070 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
10080 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
10090 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
100a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
100b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
100c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
100d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
100e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
100f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
10100 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
10110 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
10120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10130 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
10140 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
10150 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
10160 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
10170 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
10180 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
10190 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
101a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
101b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
101c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
101d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
101e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
101f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
10200 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
10210 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
10220 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
10230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10240 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
10250 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
10260 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
10270 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
10280 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
10290 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
102a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
102b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
102c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
102d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
102e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
102f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10300 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
10310 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10320 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
10330 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
10340 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
10350 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
10360 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
10370 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
10380 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
10390 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
103a0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
103b0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
103c0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
103d0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
103e0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
103f0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
10400 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
10410 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
10420 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
10430 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
10440 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
10450 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
10460 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
10470 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
10480 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
10490 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
104a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
104b0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
104c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
104d0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
104e0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
104f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
10500 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
10510 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
10520 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
10530 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
10540 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
10550 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
10560 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
10570 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
10580 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
10590 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
105a0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
105b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
105c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
105d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
105e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
105f0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
10600 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
10610 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
10620 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
10630 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
10640 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
10650 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
10660 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
10670 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
10680 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
10690 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
106a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
106b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
106c0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
106d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
106e0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
106f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10700 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
10710 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
10720 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
10730 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
10740 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
10750 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
10760 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
10770 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
10780 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
10790 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
107a0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
107b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
107c0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
107d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
107e0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
107f0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
10800 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
10810 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
10820 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
10830 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
10840 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
10850 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
10860 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
10870 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
10880 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
10890 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
108a0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
108b0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
108c0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
108d0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
108e0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
108f0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
10900 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
10910 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
10920 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
10930 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
10940 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
10950 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
10960 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
10970 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
10980 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
10990 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
109a0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
109b0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
109c0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
109d0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
109e0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
109f0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
10a00 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
10a10 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
10a20 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
10a30 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
10a40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
10a50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
10a60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
10a70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
10a80 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
10a90 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
10aa0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
10ab0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
10ac0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
10ad0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
10ae0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
10af0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
10b00 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
10b10 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
10b20 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
10b30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
10b40 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
10b50 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
10b60 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
10b70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
10b80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
10b90 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
10ba0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
10bb0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
10bc0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
10bd0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
10be0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
10bf0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10c00 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
10c10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10c20 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
10c30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10c40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
10c50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
10c60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
10c70 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
10c80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
10c90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10ca0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
10cb0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
10cc0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
10cd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
10ce0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
10cf0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
10d00 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10d10 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
10d20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
10d30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
10d40 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
10d50 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
10d60 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
10d70 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
10d80 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
10d90 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
10da0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
10db0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
10dc0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
10dd0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
10de0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
10df0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
10e00 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
10e10 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
10e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
10e30 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
10e40 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
10e50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10e60 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
10e70 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
10e80 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
10e90 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
10ea0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
10eb0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
10ec0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
10ed0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
10ee0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
10ef0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
10f00 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
10f10 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
10f20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
10f30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
10f40 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
10f50 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
10f60 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
10f70 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
10f80 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
10f90 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
10fa0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
10fb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
10fc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
10fd0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
10fe0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
10ff0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
11000 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
11010 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
11020 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
11030 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
11040 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
11050 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11060 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
11070 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11080 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
11090 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
110a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
110b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
110c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
110d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
110e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
110f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
11100 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11110 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11120 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
11130 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
11140 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
11150 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
11160 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
11170 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
11180 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
11190 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
111a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
111b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
111c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
111d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
111e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
111f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11200 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
11210 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11220 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11230 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11240 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11250 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11260 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11270 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
11280 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
11290 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
112a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
112b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
112c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
112d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
112e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
112f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11300 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
11310 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11320 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
11330 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11340 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
11350 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11360 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
11370 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11380 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
11390 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
113a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
113b0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
113c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
113d0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
113e0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
113f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11400 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
11410 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
11420 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
11430 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
11440 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
11450 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
11460 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
11470 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
11480 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
11490 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
114a0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
114b0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
114c0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
114d0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
114e0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
114f0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
11500 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11510 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11520 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11530 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11540 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11550 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11560 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
11570 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
11580 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
11590 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
115a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
115b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
115c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
115d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
115e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
115f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
11600 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
11610 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
11620 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11630 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
11640 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11650 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
11660 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11670 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
11680 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
11690 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
116a0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
116b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
116c0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
116d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
116e0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
116f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
11700 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
11710 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
11720 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
11730 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
11740 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
11750 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
11760 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
11770 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
11780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11790 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
117a0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
117b0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
117c0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
117d0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
117e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
117f0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
11800 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
11810 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
11820 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
11830 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
11840 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
11850 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
11860 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
11880 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
11890 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
118a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
118b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
118c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
118d0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
118e0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
118f0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
11900 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
11910 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
11920 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
11930 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
11940 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
11950 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
11960 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
11970 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
11980 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
11990 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
119a0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
119b0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
119c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
119d0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
119e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
119f0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
11a00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11a10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11a20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11a30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11a40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
11a50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
11a60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
11a70 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
11a80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
11a90 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11aa0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
11ab0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
11ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11ad0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
11ae0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11af0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
11b00 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
11b10 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
11b20 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
11b30 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
11b40 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
11b50 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
11b60 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
11b70 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
11b80 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
11b90 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
11ba0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
11bb0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
11bc0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
11bd0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
11be0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
11bf0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
11c00 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
11c10 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
11c20 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
11c30 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
11c40 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
11c50 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
11c60 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
11c70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
11c80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
11c90 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
11ca0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
11cb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
11cc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
11cd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
11ce0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
11cf0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
11d00 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
11d10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
11d20 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
11d30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
11d40 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
11d50 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
11d60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
11d70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
11d80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
11d90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
11da0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
11db0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
11dc0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
11dd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
11de0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
11df0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
11e00 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
11e10 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
11e20 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
11e30 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
11e40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11e50 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
11e60 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
11e70 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
11e80 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
11e90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
11ea0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
11eb0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
11ec0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
11ed0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
11ee0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
11ef0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
11f00 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
11f10 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
11f20 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
11f30 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11f40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
11f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
11f60 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
11f70 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
11f80 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
11f90 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11fa0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
11fb0 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
11fc0 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
11fd0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
11fe0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
11ff0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
12000 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
12010 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
12020 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
12030 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
12040 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12050 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
12060 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
12070 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
12080 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
12090 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
120a0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
120b0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
120c0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
120d0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
120e0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
120f0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
12100 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
12110 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
12120 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
12130 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
12140 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
12150 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
12160 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
12170 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
12180 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
12190 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
121a0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
121b0 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
121c0 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
121d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
121e0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
121f0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
12200 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12210 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
12220 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
12230 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
12240 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
12250 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
12260 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
12270 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
12280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12290 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
122a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
122b0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
122c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
122d0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
122e0 4f 4e 46 4e 49 47 5f 47 45 54 50 43 41 43 48 45  ONFNIG_GETPCACHE
122f0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
12300 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
12310 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
12320 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
12330 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
12340 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
12350 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
12360 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
12370 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
12380 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
12390 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
123a0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
123b0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
123c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
123d0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
123e0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
123f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12400 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
12410 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
12420 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12430 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
12440 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
12450 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
12460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12470 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
12480 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
12490 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
124a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
124b0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
124c0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
124d0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
124e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
124f0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12500 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
12510 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
12520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12530 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
12540 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
12550 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
12560 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
12570 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12580 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
12590 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
125a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
125b0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
125c0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
125d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
125e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
125f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12600 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
12610 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
12620 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
12630 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
12640 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
12650 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
12660 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
12670 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12680 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
12690 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
126a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
126b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
126c0 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
126d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
126e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
126f0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
12700 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
12710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
12720 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
12730 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
12740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12750 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
12760 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
12770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12780 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
12790 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
127a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
127b0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
127c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
127d0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
127e0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
127f0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a  methods2* */../*
12800 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
12810 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
12820 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
12830 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
12840 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12850 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12860 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12870 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12880 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12890 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
128a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
128b0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
128c0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
128d0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
128e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
128f0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
12900 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
12910 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
12920 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
12930 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
12940 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
12950 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
12960 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
12970 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
12980 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
12990 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
129a0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
129b0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
129c0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
129d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
129e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
129f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12a00 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12a10 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12a20 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12a30 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12a40 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12a50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12a60 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
12a70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12a80 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
12a90 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
12aa0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
12ab0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
12ac0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
12ad0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
12ae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12af0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
12b00 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
12b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
12b20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
12b30 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
12b40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
12b50 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12b60 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
12b70 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
12b80 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
12b90 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
12ba0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
12bb0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
12bc0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
12bd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12be0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
12bf0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
12c00 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
12c10 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
12c20 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
12c30 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
12c40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
12c50 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
12c60 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
12c70 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
12c80 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
12c90 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
12ca0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
12cb0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
12cc0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
12cd0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
12ce0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12cf0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
12d00 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
12d10 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
12d20 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
12d30 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
12d40 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
12d50 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
12d60 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
12d70 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
12d80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12d90 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
12da0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
12db0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
12dc0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
12dd0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
12de0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
12df0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
12e00 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
12e10 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
12e20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
12e30 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
12e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12e50 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
12e60 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
12e70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
12e80 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
12e90 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
12ea0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
12eb0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
12ec0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
12ed0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
12ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
12ef0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
12f00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
12f10 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
12f20 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
12f30 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
12f40 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
12f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
12f60 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
12f70 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
12f80 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
12f90 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
12fa0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
12fb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
12fc0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
12fd0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
12fe0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
12ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13000 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
13010 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
13020 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
13030 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
13040 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
13050 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
13060 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
13070 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
13080 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
13090 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
130a0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
130b0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
130c0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
130d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
130e0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
130f0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
13100 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
13110 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
13120 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
13130 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
13140 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
13150 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
13160 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
13170 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
13180 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
13190 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
131a0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
131b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
131c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
131d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
131e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
131f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
13200 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
13210 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
13220 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
13230 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
13240 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
13250 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
13260 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13270 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
13280 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
13290 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
132a0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
132b0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
132c0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
132d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
132e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
132f0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
13300 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
13310 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
13320 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
13330 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
13340 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
13350 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
13360 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
13370 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13380 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
13390 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
133a0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
133b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
133c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
133d0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
133e0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
133f0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
13400 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
13410 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13420 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
13430 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
13440 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
13450 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
13460 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
13470 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
13480 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
13490 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
134a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
134b0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
134c0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
134d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
134e0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
134f0 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
13500 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
13510 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
13520 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
13530 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
13540 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
13550 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
13560 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
13570 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
13580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
13590 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
135a0 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
135b0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
135c0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
135d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
135e0 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
135f0 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
13600 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
13610 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
13620 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
13630 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
13640 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
13650 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
13660 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
13670 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
13680 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
13690 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
136a0 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
136b0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
136c0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
136d0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
136e0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
136f0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
13700 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
13710 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
13720 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
13730 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
13740 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
13750 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
13760 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
13770 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
13780 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
13790 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
137a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
137b0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
137c0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
137d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
137e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
137f0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
13800 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
13810 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
13820 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
13830 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
13840 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
13850 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
13860 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
13870 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
13880 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
13890 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  m the [database 
138a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69  connection].** i
138b0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
138c0 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51  ment.  ^As of SQ
138d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
138e0 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .7, this routine
138f0 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65  s.** records the
13900 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
13910 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e  id of both ordin
13920 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b  ary tables and [
13930 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
13940 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
13950 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
13960 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
13970 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
13980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13990 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
139a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
139b0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
139c0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
139d0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
139e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
139f0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
13a00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
13a10 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
13a20 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
13a30 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
13a40 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
13a50 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
13a60 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
13a70 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
13a80 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
13a90 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
13aa0 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
13ab0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13ac0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
13ad0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
13ae0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
13af0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
13b00 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
13b10 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
13b20 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
13b30 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
13b40 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
13b50 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
13b60 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
13b70 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
13b80 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
13b90 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
13ba0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
13bb0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
13bc0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
13bd0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
13be0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
13bf0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
13c00 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
13c10 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
13c20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
13c30 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
13c40 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
13c50 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
13c60 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
13c70 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
13c80 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
13c90 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
13ca0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
13cb0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
13cc0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
13cd0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
13ce0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
13cf0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
13d00 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
13d10 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
13d20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
13d30 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
13d40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
13d50 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
13d60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
13d70 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
13d80 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
13d90 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
13da0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
13db0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
13dc0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
13dd0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
13de0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
13df0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
13e00 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
13e10 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
13e20 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
13e30 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
13e40 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
13e50 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
13e60 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
13e70 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
13e80 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
13e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
13ea0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
13eb0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
13ec0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
13ed0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
13ee0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
13ef0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
13f00 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
13f10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13f20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
13f30 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
13f40 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
13f50 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
13f60 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
13f70 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
13f80 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
13f90 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
13fa0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
13fb0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
13fc0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
13fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13fe0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
13ff0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
14000 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
14010 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
14020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
14030 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
14040 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
14050 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
14060 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
14070 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
14080 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
14090 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
140a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
140b0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
140c0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
140d0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
140e0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
140f0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
14100 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
14110 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
14120 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
14130 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
14140 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
14150 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
14160 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
14170 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
14180 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
14190 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
141a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
141b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
141c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
141d0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
141e0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
141f0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
14200 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
14210 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
14220 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
14230 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
14240 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
14250 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
14260 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
14270 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
14280 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
14290 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
142a0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
142b0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
142c0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
142d0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
142e0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
142f0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
14300 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
14310 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
14320 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
14330 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
14340 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
14350 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
14360 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
14370 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
14380 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
14390 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
143a0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
143b0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
143c0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
143d0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
143e0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
143f0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
14400 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
14410 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
14420 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
14430 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
14440 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
14450 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
14460 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
14470 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
14480 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
14490 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
144a0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
144b0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
144c0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
144d0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
144e0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
144f0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
14500 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
14510 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
14520 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
14530 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
14540 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
14550 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
14560 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
14570 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
14580 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
14590 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
145a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
145b0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
145c0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
145d0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
145e0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
145f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
14600 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14610 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
14620 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
14630 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
14640 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
14650 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
14660 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
14670 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14680 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
14690 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
146a0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
146b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
146c0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
146d0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
146e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
146f0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14700 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
14710 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
14720 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
14730 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
14740 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
14750 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
14760 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
14770 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
14780 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
14790 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
147a0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
147b0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
147c0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
147d0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
147e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
147f0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
14800 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
14810 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
14820 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
14830 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
14840 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
14850 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
14860 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
14870 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
14880 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
14890 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
148a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
148b0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
148c0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
148d0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
148e0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
148f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
14900 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
14910 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
14920 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
14930 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
14940 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
14950 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
14960 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
14970 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
14980 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
14990 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
149a0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
149b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
149c0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
149d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
149e0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
149f0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
14a00 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
14a10 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14a20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14a30 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
14a40 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
14a50 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
14a60 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
14a70 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
14a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14a90 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
14aa0 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
14ab0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
14ac0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
14ad0 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
14ae0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
14af0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
14b00 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
14b10 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
14b20 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
14b30 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14b40 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
14b50 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
14b60 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
14b70 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
14b80 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
14b90 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
14ba0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
14bb0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
14bc0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
14bd0 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
14be0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
14bf0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
14c00 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
14c10 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
14c20 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
14c30 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
14c40 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
14c50 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
14c60 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
14c70 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
14c80 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
14c90 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
14ca0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
14cb0 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
14cc0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
14cd0 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
14ce0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
14cf0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
14d00 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
14d10 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
14d20 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
14d30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
14d40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
14d50 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
14d60 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
14d70 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
14d80 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
14d90 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
14da0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
14db0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
14dc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
14dd0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
14de0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
14df0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
14e00 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
14e10 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
14e20 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
14e30 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
14e40 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
14e50 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
14e60 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
14e70 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
14e80 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
14e90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14ea0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
14eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14ec0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
14ed0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
14ee0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
14ef0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
14f00 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
14f10 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
14f20 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
14f30 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
14f40 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
14f50 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
14f60 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
14f70 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
14f80 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
14f90 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
14fa0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
14fb0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
14fc0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
14fd0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
14fe0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
14ff0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
15000 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
15010 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
15020 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
15030 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
15040 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
15050 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
15060 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
15070 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
15080 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
15090 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
150a0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
150b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
150c0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
150d0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
150e0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
150f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15100 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
15110 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
15120 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
15130 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
15140 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
15150 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
15160 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
15170 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
15180 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
15190 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
151a0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
151b0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
151c0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
151d0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
151e0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
151f0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
15200 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
15210 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
15220 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
15230 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
15240 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
15250 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
15260 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
15270 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
15280 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
15290 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
152a0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
152b0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
152c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
152d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
152e0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
152f0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
15300 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
15310 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
15320 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
15330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15340 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
15350 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
15360 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
15370 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
15380 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
15390 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
153a0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
153b0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
153c0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
153d0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
153e0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
153f0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
15400 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
15410 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
15420 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
15430 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
15440 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
15450 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
15460 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
15470 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
15480 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
15490 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
154a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
154b0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
154c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
154d0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
154e0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
154f0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
15500 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
15510 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
15520 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
15530 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
15540 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
15550 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
15560 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
15570 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
15580 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
15590 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
155a0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
155b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
155c0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
155d0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
155e0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
155f0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
15600 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
15610 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15620 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
15630 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
15640 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
15650 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
15660 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
15670 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
15680 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
15690 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
156a0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
156b0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
156c0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
156d0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
156e0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
156f0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
15700 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
15710 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
15720 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
15730 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
15740 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
15750 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
15760 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
15770 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
15780 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
15790 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
157a0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
157b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
157c0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
157d0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
157e0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
157f0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
15800 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
15810 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
15820 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
15830 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
15840 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
15850 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
15860 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
15870 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
15880 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
15890 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
158a0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
158b0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
158c0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
158d0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
158e0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
158f0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
15900 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
15910 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
15920 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
15930 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
15940 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
15950 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
15960 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
15970 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
15980 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
15990 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
159a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
159b0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
159c0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
159d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
159e0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
159f0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
15a00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
15a10 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
15a20 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
15a30 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
15a40 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
15a50 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
15a60 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
15a70 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
15a80 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
15a90 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
15aa0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15ab0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
15ac0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
15ad0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
15ae0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
15af0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15b00 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
15b10 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
15b20 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
15b30 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
15b40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
15b50 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
15b60 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
15b70 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
15b80 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
15b90 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
15ba0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
15bb0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
15bc0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
15bd0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
15be0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
15bf0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
15c00 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
15c10 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
15c20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
15c30 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
15c40 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
15c50 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
15c60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15c70 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
15c80 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
15c90 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15ca0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
15cb0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
15cc0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
15cd0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
15ce0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
15cf0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
15d00 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
15d10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15d20 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
15d30 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
15d40 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
15d50 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
15d60 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
15d70 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
15d80 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
15d90 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
15da0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
15db0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
15dc0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
15dd0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
15de0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15df0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
15e00 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
15e10 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
15e20 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
15e30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
15e40 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
15e50 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
15e60 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
15e70 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
15e80 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
15e90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15ea0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
15eb0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
15ec0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
15ed0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
15ee0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15ef0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
15f00 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
15f10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15f20 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
15f30 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
15f40 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
15f50 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
15f60 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
15f70 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
15f80 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
15f90 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
15fa0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
15fb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
15fc0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
15fd0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
15fe0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
15ff0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
16000 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
16010 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
16020 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
16030 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
16040 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
16050 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
16060 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
16070 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
16080 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
16090 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
160a0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
160b0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
160c0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
160d0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
160e0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
160f0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
16100 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
16110 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
16120 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
16130 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
16140 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
16150 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
16160 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
16170 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
16180 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
16190 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
161a0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
161b0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
161c0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
161d0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
161e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
161f0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
16200 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
16210 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
16220 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
16230 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
16240 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
16250 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
16260 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
16270 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
16280 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
16290 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
162a0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
162b0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
162c0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
162d0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
162e0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
162f0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
16300 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
16310 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
16320 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
16330 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
16340 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
16350 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
16360 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
16370 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
16380 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
16390 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
163a0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
163b0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
163c0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
163d0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
163e0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
163f0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
16400 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
16410 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
16420 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
16430 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
16440 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
16450 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
16460 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
16470 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
16480 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
16490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
164a0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
164b0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
164c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
164d0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
164e0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
164f0 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
16500 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
16510 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
16520 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
16530 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
16540 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
16550 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
16560 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
16570 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
16580 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
16590 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
165a0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
165b0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
165c0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
165d0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
165e0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
165f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
16600 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
16610 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
16620 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
16630 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
16640 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
16650 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
16660 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
16670 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
16680 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
16690 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
166a0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
166b0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
166c0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
166d0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
166e0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
166f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16700 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
16710 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
16720 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
16730 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
16740 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
16750 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
16760 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
16770 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
16780 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
16790 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
167a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
167b0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
167c0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
167d0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
167e0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
167f0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
16800 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
16810 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
16820 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
16830 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
16840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
16850 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
16860 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
16870 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
16880 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
16890 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
168a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
168b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
168c0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
168d0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
168e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
168f0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
16900 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
16910 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
16920 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
16930 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
16940 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
16950 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
16960 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
16970 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
16980 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
16990 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
169a0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
169b0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
169c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
169d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
169e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
169f0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
16a00 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
16a10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
16a20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
16a30 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
16a40 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
16a50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16a60 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
16a70 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
16a80 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
16a90 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
16aa0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
16ab0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
16ac0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
16ad0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
16ae0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
16af0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
16b00 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
16b10 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
16b20 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
16b30 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
16b40 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
16b50 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
16b60 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
16b70 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
16b80 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
16b90 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
16ba0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
16bb0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
16bc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
16bd0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
16be0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
16bf0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
16c00 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
16c10 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
16c20 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
16c30 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
16c40 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
16c50 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
16c60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
16c70 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
16c80 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
16c90 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
16ca0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
16cb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16cc0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
16cd0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
16ce0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
16cf0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
16d00 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
16d10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
16d20 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
16d30 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
16d40 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
16d50 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
16d60 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
16d70 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
16d80 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
16d90 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
16da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16db0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
16dc0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
16dd0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
16de0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
16df0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
16e00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
16e10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
16e20 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
16e30 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
16e40 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
16e50 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
16e60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
16e70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
16e80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
16e90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
16ea0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
16eb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
16ec0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
16ed0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
16ee0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
16ef0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
16f00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
16f10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
16f20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
16f30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
16f40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
16f50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
16f60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
16f70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
16f80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
16f90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
16fa0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
16fb0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
16fc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
16fd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
16fe0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
16ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
17000 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
17010 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
17020 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
17030 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
17040 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
17050 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
17060 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
17070 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
17080 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
17090 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
170a0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
170b0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
170c0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
170d0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
170e0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
170f0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
17100 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
17110 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
17120 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
17130 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
17140 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
17150 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
17160 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
17170 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
17180 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
17190 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
171a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
171b0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
171c0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
171d0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
171e0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
171f0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
17200 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
17210 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
17220 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
17230 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17240 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
17250 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
17260 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
17270 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
17280 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
17290 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
172a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
172b0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
172c0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
172d0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
172e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
172f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17300 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
17310 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
17320 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
17330 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
17340 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
17350 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
17360 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
17370 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
17380 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
17390 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
173a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
173b0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
173c0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
173d0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
173e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
173f0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
17400 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
17410 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
17420 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
17430 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
17440 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
17450 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
17460 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
17470 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17480 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
17490 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
174a0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
174b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
174c0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
174d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
174e0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
174f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17500 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
17510 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17520 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
17530 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
17540 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
17550 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
17560 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
17570 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
17580 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17590 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
175a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
175b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
175c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
175d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
175e0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
175f0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
17600 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
17610 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
17620 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
17630 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
17640 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
17650 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
17660 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
17670 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
17680 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
17690 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
176a0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
176b0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
176c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
176d0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
176e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
176f0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
17700 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17710 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
17720 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
17730 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
17740 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
17750 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
17760 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
17770 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
17780 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
17790 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
177a0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
177b0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
177c0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
177d0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
177e0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
177f0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
17800 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
17810 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
17820 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
17830 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
17840 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
17850 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
17860 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17870 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
17880 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
17890 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
178a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
178b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
178c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
178d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
178e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
178f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
17900 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
17910 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
17920 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
17930 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
17940 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
17950 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
17960 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
17970 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
17980 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
17990 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
179a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
179b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
179c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
179d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
179e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
179f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
17a00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
17a10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17a20 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
17a30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
17a40 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
17a50 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
17a60 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
17a70 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
17a80 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
17a90 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
17aa0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
17ab0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
17ac0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
17ad0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
17ae0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
17af0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
17b00 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
17b10 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
17b20 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
17b30 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
17b40 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
17b50 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
17b60 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
17b70 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
17b80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
17b90 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
17ba0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
17bb0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
17bc0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
17bd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
17be0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
17bf0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
17c00 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
17c10 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
17c20 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
17c30 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
17c40 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
17c50 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
17c60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
17c70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
17c80 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
17c90 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
17ca0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
17cb0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
17cc0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
17cd0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
17ce0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
17cf0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
17d00 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
17d10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
17d20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
17d30 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
17d40 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
17d50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
17d60 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
17d70 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
17d80 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
17d90 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
17da0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
17db0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
17dc0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
17dd0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
17de0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
17df0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
17e00 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
17e10 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
17e20 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
17e30 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
17e40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17e50 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
17e60 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
17e70 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
17e80 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
17e90 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
17ea0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
17eb0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
17ec0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
17ed0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
17ee0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
17ef0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
17f00 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
17f10 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
17f20 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
17f30 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
17f40 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
17f50 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
17f60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
17f70 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
17f80 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
17f90 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
17fa0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
17fb0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
17fc0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
17fd0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
17fe0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
17ff0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
18000 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
18010 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
18020 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
18030 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
18040 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
18050 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
18060 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
18070 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
18080 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
18090 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
180a0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
180b0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
180c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
180d0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
180e0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
180f0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
18100 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
18110 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
18120 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
18130 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
18140 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
18150 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
18160 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
18170 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
18180 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
18190 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
181a0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
181b0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
181c0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
181d0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
181e0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
181f0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
18200 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
18210 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
18220 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
18230 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
18240 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
18250 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
18260 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
18270 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
18280 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
18290 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
182a0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
182b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
182c0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
182d0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
182e0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
182f0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
18300 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
18310 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
18320 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
18330 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
18340 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
18350 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
18360 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
18370 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
18380 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
18390 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
183a0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
183b0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
183c0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
183d0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
183e0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
183f0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
18400 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
18410 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
18420 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
18430 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
18440 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
18450 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
18460 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
18470 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
18480 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
18490 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
184a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
184b0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
184c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
184d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
184e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
184f0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
18500 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
18510 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
18520 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
18530 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18540 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
18550 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
18560 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
18570 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
18580 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
18590 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
185a0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
185b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
185c0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
185d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
185e0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
185f0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
18600 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
18610 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
18620 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
18630 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
18640 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
18650 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
18660 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18670 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
18680 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
18690 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
186a0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
186b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
186c0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
186d0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
186e0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
186f0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
18700 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
18710 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
18720 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18730 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
18740 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
18750 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
18760 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
18770 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18780 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
18790 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
187a0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
187b0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
187c0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
187d0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
187e0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
187f0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
18800 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
18810 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
18820 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
18830 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
18840 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
18850 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
18860 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
18870 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
18880 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
18890 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
188a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
188b0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
188c0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
188d0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
188e0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
188f0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
18900 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
18910 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
18920 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
18930 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
18940 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18950 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18960 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18970 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18980 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
18990 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
189a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
189b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
189c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
189d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
189e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
189f0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
18a00 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
18a10 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
18a20 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
18a30 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
18a40 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
18a50 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
18a60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
18a70 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
18a80 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
18a90 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
18aa0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
18ab0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
18ac0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
18ad0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
18ae0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
18af0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
18b00 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
18b10 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
18b20 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
18b30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
18b40 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
18b50 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
18b60 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
18b70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
18b80 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
18b90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
18ba0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
18bb0 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
18bc0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
18bd0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
18be0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
18bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18c00 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
18c10 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
18c20 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
18c30 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
18c40 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
18c50 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
18c60 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
18c70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18c80 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
18c90 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
18ca0 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
18cb0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
18cc0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
18cd0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
18ce0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
18cf0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
18d00 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
18d10 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
18d20 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
18d30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18d40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18d50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
18d60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
18d70 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
18d80 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
18d90 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
18da0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
18db0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
18dc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
18dd0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
18de0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
18df0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
18e00 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
18e10 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
18e20 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
18e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
18e40 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
18e50 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
18e60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18e70 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
18e80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
18e90 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
18ea0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
18eb0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
18ec0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
18ed0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18ee0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
18ef0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
18f00 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
18f10 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
18f20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
18f30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18f40 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
18f50 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
18f60 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
18f70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
18f80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
18f90 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
18fa0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
18fb0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
18fc0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
18fd0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
18fe0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
18ff0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
19000 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
19010 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
19020 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
19030 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
19040 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
19050 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
19060 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
19070 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
19080 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
19090 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
190a0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
190b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
190c0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
190d0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
190e0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
190f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
19100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
19110 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19120 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
19130 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19140 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
19150 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
19160 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
19170 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
19180 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
19190 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
191a0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
191b0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
191c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
191d0 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
191e0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
191f0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
19200 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
19220 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
19230 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
19240 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
19250 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
19260 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19270 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
19280 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
19290 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
192a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
192b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
192c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
192d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
192e0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
192f0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
19300 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
19310 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
19320 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
19330 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
19340 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
19350 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19360 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19370 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
19380 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
19390 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
193a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
193b0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
193c0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
193d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
193e0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
193f0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
19400 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
19410 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
19420 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
19430 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
19440 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
19450 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
19460 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
19470 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
19480 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
19490 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
194a0 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
194b0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
194c0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
194d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
194e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
194f0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
19500 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
19510 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
19520 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
19530 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
19540 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
19550 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
19560 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
19570 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
19580 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
19590 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
195a0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
195b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
195c0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
195d0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
195e0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
195f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
19600 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
19610 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
19620 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
19630 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
19640 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
19650 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
19660 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
19670 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
19680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
19690 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
196a0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
196b0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
196c0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
196d0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
196e0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
196f0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
19700 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
19710 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
19720 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
19730 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
19740 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
19750 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
19760 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
19770 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
19780 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
19790 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
197a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
197b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
197c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
197d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
197e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
197f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
19800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
19810 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
19820 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
19830 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
19840 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
19850 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
19860 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
19870 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
19880 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
19890 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
198a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
198b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
198c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
198d0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
198e0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
198f0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
19900 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
19910 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
19920 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
19930 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
19940 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
19950 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
19960 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
19970 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
19980 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
19990 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
199a0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
199b0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
199c0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
199d0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
199e0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
199f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
19a00 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
19a10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
19a20 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
19a30 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
19a40 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
19a50 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
19a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19a70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
19a80 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
19a90 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
19aa0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
19ab0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
19ac0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
19ad0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
19ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19af0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
19b00 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
19b10 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
19b20 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
19b30 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
19b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19b50 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
19b60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
19b70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
19b80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
19ba0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
19bb0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
19bc0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
19bd0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
19be0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
19bf0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
19c00 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
19c10 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
19c20 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
19c30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19c40 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
19c50 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
19c60 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
19c70 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
19c80 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19c90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19ca0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
19cb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19cc0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
19cd0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
19ce0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
19cf0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
19d00 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
19d10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
19d20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
19d30 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
19d40 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
19d50 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
19d60 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
19d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19d80 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
19d90 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
19da0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
19db0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
19dc0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
19dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19de0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
19df0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
19e00 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
19e10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19e20 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
19e30 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
19e40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
19e50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
19e60 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
19e70 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
19e80 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
19e90 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
19ea0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19eb0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
19ec0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
19ed0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
19ee0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
19ef0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
19f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
19f10 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
19f20 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
19f30 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
19f40 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
19f50 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
19f60 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
19f70 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
19f80 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
19f90 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
19fa0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
19fb0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
19fc0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
19fd0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
19fe0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
19ff0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1a000 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1a010 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1a020 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1a030 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1a040 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1a050 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1a060 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1a070 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1a080 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1a090 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1a0a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1a0b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1a0c0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1a0d0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1a0e0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
1a0f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
1a100 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
1a110 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
1a120 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
1a130 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
1a140 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
1a150 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
1a160 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1a170 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
1a180 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1a190 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
1a1a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a1b0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
1a1c0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
1a1d0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
1a1e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1a1f0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1a200 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1a210 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1a220 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1a230 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1a240 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1a250 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1a260 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1a270 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1a280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1a290 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1a2a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1a2b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a2c0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1a2d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a2e0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1a2f0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1a300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1a310 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1a320 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1a330 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1a340 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1a350 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1a360 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1a370 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1a380 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1a390 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1a3a0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1a3b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1a3c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a3d0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1a3e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a3f0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1a400 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1a410 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1a420 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1a430 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1a440 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1a450 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1a460 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1a470 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1a480 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1a490 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1a4a0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1a4b0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1a4c0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1a4d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1a4e0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1a4f0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1a500 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1a510 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1a520 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1a530 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1a540 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1a550 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1a560 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1a570 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1a580 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1a590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1a5a0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1a5b0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1a5c0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1a5d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1a5e0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1a5f0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1a600 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1a610 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1a620 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1a630 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1a640 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a650 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1a660 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1a670 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1a680 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1a690 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1a6a0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1a6b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1a6c0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1a6d0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1a6e0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1a6f0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1a700 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1a710 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1a720 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1a730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a740 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1a750 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1a760 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1a770 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1a780 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1a790 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1a7a0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1a7b0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1a7c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a7d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a7e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a7f0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a800 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1a810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a820 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a830 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1a840 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1a850 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1a860 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a870 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1a880 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a890 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a8a0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1a8b0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1a8c0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1a8d0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1a8e0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1a8f0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1a900 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1a910 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a920 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a930 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1a940 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1a950 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1a960 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a970 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1a980 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1a990 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1a9a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a9b0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1a9c0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1a9d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a9e0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1a9f0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1aa00 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1aa10 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1aa20 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1aa30 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1aa40 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1aa50 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1aa60 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1aa70 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1aa80 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1aa90 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1aaa0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1aab0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1aac0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1aad0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1aae0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1aaf0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ab00 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1ab10 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1ab20 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1ab30 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ab40 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1ab50 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1ab60 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1ab70 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1ab80 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1ab90 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1aba0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1abb0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1abc0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1abd0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1abe0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1abf0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1ac00 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1ac10 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1ac20 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1ac30 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ac40 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1ac50 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1ac60 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1ac70 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1ac80 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1ac90 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1aca0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1acb0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1acc0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1acd0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1ace0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1acf0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1ad00 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1ad10 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1ad20 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1ad30 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1ad40 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1ad50 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1ad60 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1ad70 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1ad80 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1ad90 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1ada0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1adb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1adc0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1add0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1ade0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1adf0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1ae00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1ae10 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1ae20 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1ae30 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1ae40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ae50 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1ae60 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1ae70 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1ae80 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1ae90 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1aea0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1aeb0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1aec0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1aed0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1aee0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1aef0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1af00 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1af10 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1af20 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1af30 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1af40 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1af50 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1af60 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1af70 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1af80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1af90 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1afa0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1afb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1afc0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1afd0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1afe0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1aff0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b000 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1b010 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1b020 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1b030 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1b040 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1b050 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b060 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1b070 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1b080 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1b090 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b0a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1b0b0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1b0c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1b0d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1b0e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b0f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1b100 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1b110 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1b120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1b130 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1b140 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1b150 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1b160 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1b170 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b180 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1b190 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1b1a0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1b1b0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1b1c0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1b1d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b1e0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1b1f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1b200 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1b210 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1b220 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1b230 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1b240 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1b250 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1b260 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1b270 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1b280 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1b290 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b2a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1b2b0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1b2c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1b2d0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1b2e0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1b2f0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1b300 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1b310 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1b320 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1b330 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1b340 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1b350 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1b360 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1b370 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1b380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b390 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1b3a0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1b3b0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1b3c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1b3d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b3e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1b3f0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1b400 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1b410 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1b420 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1b430 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1b440 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1b450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1b460 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1b470 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1b480 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b490 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1b4a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1b4b0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1b4c0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1b4d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1b4e0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1b4f0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1b500 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1b510 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1b520 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1b530 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1b540 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1b550 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b560 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1b570 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1b580 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b590 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1b5a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1b5b0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1b5c0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1b5d0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1b5e0 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1b5f0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1b600 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1b610 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1b620 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1b630 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1b640 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1b650 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1b660 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1b670 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1b680 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1b690 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1b6a0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1b6b0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1b6c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1b6d0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1b6e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1b6f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1b700 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1b710 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1b720 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1b730 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1b740 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1b750 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1b760 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1b770 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1b780 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1b790 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b7a0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1b7b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1b7c0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1b7d0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1b7e0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1b7f0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1b800 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1b810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b820 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1b830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1b840 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1b850 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1b860 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1b870 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1b880 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1b890 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1b8a0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1b8b0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1b8c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1b8d0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1b8e0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1b8f0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1b900 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1b910 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1b920 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1b930 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1b940 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1b950 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b960 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1b970 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1b980 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1b990 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1b9a0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1b9b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1b9c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b9d0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1b9e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1b9f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ba00 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1ba10 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ba20 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ba30 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1ba40 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1ba50 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1ba60 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ba70 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ba80 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ba90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1baa0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1bab0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1bac0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1bad0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1bae0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1baf0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1bb00 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1bb10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1bb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1bb30 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1bb40 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1bb50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1bb60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bb70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1bb80 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1bb90 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1bba0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1bbb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1bbc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1bbd0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1bbe0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1bbf0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1bc00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1bc10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1bc20 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1bc30 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1bc40 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1bc50 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1bc60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1bc70 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1bc80 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1bc90 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1bca0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bcb0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1bcc0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1bcd0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1bce0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1bcf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bd00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1bd10 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1bd20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1bd30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bd40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bd50 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1bd60 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1bd70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bd80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bd90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bda0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1bdb0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1bdc0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1bdd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bde0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bdf0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1be00 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1be10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1be20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1be30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1be40 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1be50 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1be60 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1be70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1be80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1be90 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1bea0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1beb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1bec0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bed0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bee0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1bef0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1bf00 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1bf10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1bf20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bf30 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1bf40 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1bf50 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1bf60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bf70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bf80 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1bf90 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1bfa0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1bfb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1bfc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1bfd0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1bfe0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1bff0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1c000 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1c020 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1c030 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1c040 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c050 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c060 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1c070 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1c080 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1c090 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1c0a0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1c0b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1c0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c0d0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1c0e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1c0f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1c100 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1c110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1c120 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1c130 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c140 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c150 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1c160 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1c170 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1c180 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c190 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c1a0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1c1b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1c1c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c1d0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1c1e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c1f0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1c200 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1c210 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1c220 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c230 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c240 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1c250 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1c260 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1c270 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c280 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c290 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1c2a0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1c2b0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1c2c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c2d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c2e0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1c2f0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1c300 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c310 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c330 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1c340 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1c350 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c360 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c380 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1c390 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1c3a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1c3b0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1c3c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c3d0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1c3e0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1c3f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1c400 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1c410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c420 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1c430 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1c440 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1c450 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1c460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1c470 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1c480 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1c490 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1c4a0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1c4b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1c4c0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1c4d0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1c4e0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1c4f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1c500 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1c510 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1c520 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c530 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1c540 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1c550 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1c560 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1c570 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1c580 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1c590 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c5a0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1c5b0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1c5c0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1c5d0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1c5e0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1c5f0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1c600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1c610 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1c620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c640 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1c650 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1c660 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1c670 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1c680 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1c690 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1c6a0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1c6b0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1c6c0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1c6d0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1c6e0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1c6f0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1c700 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1c710 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1c720 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1c730 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1c740 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1c750 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1c760 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1c770 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
1c780 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c790 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1c7a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c7b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c7c0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1c7d0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1c7e0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1c7f0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1c800 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1c810 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1c820 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1c830 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1c840 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1c850 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1c860 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1c870 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1c880 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1c890 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1c8a0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1c8b0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1c8c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1c8d0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1c8e0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1c8f0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1c900 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1c910 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1c920 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1c930 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1c940 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c950 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1c960 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1c970 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1c980 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1c990 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1c9a0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1c9b0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1c9c0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1c9d0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1c9e0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1c9f0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1ca00 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1ca10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1ca20 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1ca30 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1ca40 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1ca50 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1ca60 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1ca70 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1ca80 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1ca90 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1caa0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1cab0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1cac0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1cad0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1cae0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1caf0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1cb00 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1cb10 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1cb20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1cb30 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1cb40 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1cb50 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1cb60 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1cb70 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1cb80 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1cb90 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1cba0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1cbb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cbc0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1cbd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cbe0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1cbf0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1cc00 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1cc10 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1cc20 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1cc30 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1cc40 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1cc50 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1cc60 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1cc70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1cc80 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1cc90 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1cca0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1ccb0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1ccc0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1ccd0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1cce0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1ccf0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1cd00 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1cd10 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1cd20 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1cd30 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1cd40 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1cd50 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1cd60 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1cd70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd80 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1cd90 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1cda0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1cdb0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1cdc0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1cdd0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1cde0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1cdf0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1ce00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ce10 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1ce20 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1ce30 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1ce40 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1ce50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1ce60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ce70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1ce80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1ce90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1cea0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1ceb0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1cec0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1ced0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1cee0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1cef0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1cf00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cf10 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1cf20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1cf30 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1cf40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1cf50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1cf60 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1cf70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1cf80 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1cf90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cfa0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cfb0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1cfc0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1cfd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cfe0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1cff0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1d000 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1d010 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1d020 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1d030 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1d040 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1d050 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1d060 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1d070 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1d080 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1d090 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1d0a0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1d0b0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1d0c0 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1d0d0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1d0e0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1d0f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1d100 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1d110 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1d120 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1d130 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1d140 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1d150 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1d160 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1d170 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1d180 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1d190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d1a0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1d1b0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1d1c0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1d1d0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1d1e0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1d1f0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1d200 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1d210 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1d220 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1d230 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1d240 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1d250 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1d260 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1d270 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1d280 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1d290 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1d2a0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1d2b0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1d2c0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1d2d0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1d2e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d2f0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1d300 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1d310 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1d320 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1d330 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1d340 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1d350 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1d360 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1d370 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1d380 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1d390 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1d3a0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1d3b0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1d3c0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1d3d0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1d3e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1d3f0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1d400 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1d410 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1d420 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1d430 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1d440 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1d450 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1d460 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d470 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1d480 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1d490 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1d4a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1d4b0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1d4c0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1d4d0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1d4e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1d4f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d500 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1d510 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1d520 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1d530 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1d540 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1d550 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1d560 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1d570 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d580 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1d590 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1d5a0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1d5b0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1d5c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1d5d0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1d5e0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1d5f0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1d600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d610 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1d620 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1d630 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1d640 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1d650 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d660 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d670 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d680 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d690 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d6a0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1d6b0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d6c0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1d6d0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1d6e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1d6f0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
1d700 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1d710 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
1d720 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1d730 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d740 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1d750 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1d760 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1d770 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1d780 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1d790 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1d7a0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1d7b0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d7c0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1d7d0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d7e0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1d7f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1d800 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1d810 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1d820 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1d830 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1d840 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1d850 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1d860 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1d870 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1d880 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1d890 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1d8a0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1d8b0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1d8c0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1d8d0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1d8e0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1d8f0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1d900 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1d910 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1d920 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d930 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d940 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d950 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1d960 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1d970 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1d980 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1d990 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1d9a0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1d9b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1d9c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1d9d0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1d9e0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1d9f0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1da00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1da10 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1da20 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1da30 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1da40 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
1da50 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
1da60 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
1da70 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
1da80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
1da90 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
1daa0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1dab0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1dac0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1dad0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1dae0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1daf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1db00 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1db10 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1db20 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1db30 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1db40 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1db50 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1db60 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1db70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1db80 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1db90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1dba0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1dbb0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1dbc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dbd0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1dbe0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1dbf0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1dc00 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1dc10 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1dc20 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1dc30 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1dc40 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1dc50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1dc60 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1dc70 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1dc80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dc90 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1dca0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1dcb0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1dcc0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1dcd0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1dce0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1dcf0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1dd00 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1dd10 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1dd20 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1dd30 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1dd40 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1dd50 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1dd60 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1dd70 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1dd80 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1dd90 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1dda0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1ddb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
1ddc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ddd0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1dde0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ddf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1de00 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1de10 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1de20 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1de30 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1de40 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1de50 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1de60 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
1de70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1de80 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1de90 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1dea0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1deb0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1dec0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
1ded0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1dee0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1def0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1df00 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1df10 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1df20 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1df30 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1df40 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1df50 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1df60 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1df70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1df80 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1df90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1dfa0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1dfb0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1dfc0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1dfd0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1dfe0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1dff0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1e000 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e010 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1e020 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1e030 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1e040 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1e050 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1e060 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1e070 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1e080 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1e090 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1e0a0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1e0b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1e0c0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1e0d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1e0e0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1e0f0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1e100 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1e110 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1e120 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1e130 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1e140 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1e150 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1e160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e170 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1e180 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1e190 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
1e1a0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
1e1b0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
1e1c0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
1e1d0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
1e1e0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1e1f0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
1e200 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1e210 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
1e220 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
1e230 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
1e240 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
1e250 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
1e260 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1e270 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
1e280 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
1e290 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
1e2a0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
1e2b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e2c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
1e2d0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
1e2e0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
1e2f0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
1e300 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
1e310 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
1e320 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1e330 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
1e340 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
1e350 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
1e360 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
1e370 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
1e380 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1e390 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
1e3a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
1e3b0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
1e3c0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
1e3d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1e3e0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
1e3f0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
1e400 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
1e410 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
1e420 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
1e430 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
1e440 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1e450 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
1e460 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
1e470 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
1e480 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
1e490 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
1e4a0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
1e4b0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
1e4c0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
1e4d0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
1e4e0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
1e4f0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
1e500 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
1e510 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1e520 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
1e530 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
1e540 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
1e550 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
1e560 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
1e570 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
1e580 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
1e590 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
1e5a0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
1e5b0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
1e5c0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
1e5d0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
1e5e0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
1e5f0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
1e600 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
1e610 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
1e620 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
1e630 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
1e640 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
1e650 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
1e660 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
1e670 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
1e680 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
1e690 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
1e6a0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
1e6b0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1e6c0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
1e6d0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
1e6e0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
1e6f0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
1e700 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
1e710 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
1e720 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
1e730 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
1e740 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
1e750 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
1e760 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
1e770 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
1e780 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
1e790 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1e7a0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
1e7b0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
1e7c0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
1e7d0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
1e7e0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
1e7f0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
1e800 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e810 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
1e820 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
1e830 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
1e840 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
1e850 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
1e860 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
1e870 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
1e880 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
1e890 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
1e8a0 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
1e8b0 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
1e8c0 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
1e8d0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1e8e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
1e8f0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
1e900 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
1e910 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1e920 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
1e930 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
1e940 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
1e950 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
1e960 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
1e970 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
1e980 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1e990 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
1e9a0 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
1e9b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e9c0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
1e9d0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
1e9e0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
1e9f0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
1ea00 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
1ea10 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
1ea20 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
1ea30 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
1ea40 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
1ea50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1ea60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1ea70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
1ea80 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
1ea90 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
1eaa0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1eab0 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a  r "ro", "rw" or.
1eac0 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74  **     "rwc". At
1ead0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
1eae0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
1eaf0 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f  value is an erro
1eb00 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
1eb10 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
1eb20 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
1eb30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1eb40 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
1eb50 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
1eb60 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
1eb70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1eb80 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
1eb90 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
1eba0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
1ebb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
1ebc0 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66  repare_v2(). ^If
1ebd0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
1ebe0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
1ebf0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
1ec00 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ec10 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
1ec20 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
1ec30 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
1ec40 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
1ec50 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1ec60 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
1ec70 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
1ec80 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
1ec90 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
1eca0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1ecb0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
1ecc0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1ecd0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
1ece0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1ecf0 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ATE. ^If sqlite3
1ed00 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a  _open_v2() is .*
1ed10 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69  *     used, it i
1ed20 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1ed30 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1ed40 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  r the mode param
1ed50 65 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a  eter that is .**
1ed60 20 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69       less restri
1ed70 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
1ed80 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1ed90 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73   flags passed as
1eda0 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20   the third .**  
1edb0 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
1edc0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1edd0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1ede0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1edf0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1ee00 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1ee10 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1ee20 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1ee30 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1ee40 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1ee50 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1ee60 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1ee70 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1ee80 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1ee90 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1eea0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eeb0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1eec0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1eed0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1eee0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1eef0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1ef00 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1ef10 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1ef20 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1ef30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ef40 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1ef50 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1ef60 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1ef70 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1ef80 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1ef90 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1efa0 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1efb0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1efc0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1efd0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1efe0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1eff0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1f000 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1f010 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1f020 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1f030 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1f040 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1f050 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1f060 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1f070 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1f080 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1f090 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1f0a0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
1f0b0 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
1f0c0 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
1f0d0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
1f0e0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
1f0f0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1f100 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
1f110 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1f120 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
1f130 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
1f140 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
1f150 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1f160 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1f170 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1f180 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1f190 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1f1a0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1f1b0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1f1c0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1f1d0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1f1e0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1f1f0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1f200 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1f210 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1f220 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1f230 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1f240 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1f250 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1f260 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1f270 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1f280 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1f290 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1f2a0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1f2b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1f2c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f2d0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1f2e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1f2f0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1f300 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1f310 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1f320 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1f330 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1f340 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1f350 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1f360 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1f370 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1f380 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1f390 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1f3a0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1f3b0 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1f3c0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1f3d0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1f3e0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1f3f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1f400 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1f410 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1f420 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1f430 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1f440 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1f450 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1f460 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1f470 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1f480 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1f490 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1f4a0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1f4b0 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1f4c0 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1f4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1f4e0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1f4f0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1f500 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1f510 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1f520 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1f530 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1f540 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1f550 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1f560 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1f570 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1f580 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1f590 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f5a0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1f5b0 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1f5c0 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1f5d0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1f5e0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1f5f0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1f600 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1f610 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1f620 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1f630 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1f640 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1f650 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1f660 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1f670 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1f680 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1f690 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1f6a0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1f6b0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1f6c0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1f6d0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1f6e0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1f6f0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1f700 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1f710 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1f720 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
1f730 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
1f740 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
1f750 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
1f760 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
1f770 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
1f780 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
1f790 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
1f7a0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
1f7b0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
1f7c0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
1f7d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
1f7e0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
1f7f0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
1f800 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
1f810 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
1f820 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
1f830 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
1f840 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
1f850 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
1f860 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
1f870 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
1f880 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
1f890 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
1f8a0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
1f8b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1f8c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
1f8d0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1f8e0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1f8f0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1f900 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1f910 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1f920 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1f930 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f940 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1f950 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1f960 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1f970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1f980 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1f990 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1f9a0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1f9b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1f9c0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1f9d0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1f9e0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1f9f0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1fa00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1fa10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1fa20 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1fa30 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1fa40 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1fa50 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1fa60 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1fa70 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1fa80 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1fa90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1faa0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1fab0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1fac0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1fad0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1fae0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1faf0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1fb00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1fb10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1fb20 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1fb30 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1fb40 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1fb50 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1fb60 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1fb70 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1fb80 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1fb90 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1fba0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1fbb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1fbc0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1fbd0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1fbe0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1fbf0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1fc00 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1fc10 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
1fc20 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
1fc30 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
1fc40 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
1fc50 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
1fc60 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
1fc70 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
1fc80 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
1fc90 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
1fca0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
1fcb0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
1fcc0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
1fcd0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
1fce0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
1fcf0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
1fd00 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
1fd10 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
1fd20 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
1fd30 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
1fd40 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
1fd50 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
1fd60 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
1fd70 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
1fd80 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1fd90 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
1fda0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
1fdb0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1fdc0 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
1fdd0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
1fde0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
1fdf0 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
1fe00 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
1fe10 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
1fe20 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
1fe30 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
1fe40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1fe50 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
1fe60 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
1fe70 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1fe80 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
1fe90 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
1fea0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
1feb0 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
1fec0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
1fed0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
1fee0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
1fef0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
1ff00 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
1ff10 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
1ff20 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
1ff30 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1ff40 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
1ff50 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
1ff60 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
1ff70 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
1ff80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
1ff90 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
1ffa0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
1ffb0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
1ffc0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
1ffd0 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   The value of P 
1ffe0 69 73 20 74 72 75 65 20 69 66 20 69 74 20 69 73  is true if it is
1fff0 20 22 79 65 73 22 20 6f 72 20 22 74 72 75 65 22   "yes" or "true"
20000 20 6f 72 20 22 6f 6e 22 20 6f 72 20 0a 2a 2a 20   or "on" or .** 
20010 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
20020 72 20 61 6e 64 20 69 73 20 66 61 6c 73 65 20 6f  r and is false o
20030 74 68 65 72 77 69 73 65 2e 20 20 49 66 20 50 20  therwise.  If P 
20040 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 20 70  is not a query p
20050 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 6e 20 46  arameter.** on F
20060 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
20070 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
20080 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
20090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
200a0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
200b0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
200c0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
200d0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
200e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
200f0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
20100 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
20110 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
20120 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
20130 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
20140 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
20150 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
20160 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
20170 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
20180 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
20190 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
201a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
201b0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
201c0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
201d0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
201e0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
201f0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
20200 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
20210 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
20220 20 64 61 74 61 62 61 65 73 20 66 69 6c 65 20 70   databaes file p
20230 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
20240 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
20250 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
20260 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
20270 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20280 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
20290 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
202a0 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
202b0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
202c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
202d0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
202e0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
202f0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
20300 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
20310 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
20320 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
20330 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
20340 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
20350 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
20360 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20370 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
20380 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
20390 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
203a0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
203b0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
203c0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
203d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
203e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
203f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
20400 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
20410 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
20420 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
20430 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
20440 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
20450 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
20460 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
20470 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
20480 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
20490 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
204a0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
204b0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
204c0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
204d0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
204e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
204f0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
20500 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
20510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
20520 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
20530 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
20540 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
20550 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
20560 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
20570 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
20580 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
20590 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
205a0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
205b0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
205c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
205d0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
205e0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
205f0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
20600 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
20610 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
20620 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
20630 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
20640 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
20650 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
20660 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
20670 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
20680 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
20690 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
206a0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
206b0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
206c0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
206d0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
206e0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
206f0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
20700 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
20710 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
20720 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
20730 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
20740 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
20750 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
20760 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
20770 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
20780 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
20790 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
207a0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
207b0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
207c0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
207d0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
207e0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
207f0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
20800 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
20810 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
20820 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
20830 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
20840 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
20850 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
20860 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
20870 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
20880 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
20890 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
208a0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
208b0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
208c0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
208d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
208e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
208f0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
20900 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
20910 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
20920 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
20930 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
20940 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
20950 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
20960 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
20970 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
20980 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
20990 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
209a0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
209b0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
209c0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
209d0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
209e0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
209f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
20a00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
20a10 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
20a20 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
20a30 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
20a40 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
20a50 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
20a60 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
20a70 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
20a80 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
20a90 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
20aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
20ab0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
20ac0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
20ad0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20ae0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
20af0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20b00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
20b10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
20b20 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
20b30 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
20b40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
20b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20b60 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
20b70 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
20b80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
20b90 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
20ba0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
20bb0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
20bc0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
20bd0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
20be0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
20bf0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
20c00 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
20c10 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
20c20 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
20c30 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
20c40 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
20c50 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
20c60 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
20c70 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
20c80 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
20c90 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
20ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20cb0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
20cc0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
20cd0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
20ce0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
20cf0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
20d00 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
20d10 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
20d20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
20d30 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
20d40 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
20d50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
20d60 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
20d70 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
20d80 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
20d90 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
20da0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
20db0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
20dc0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
20dd0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
20de0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
20df0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
20e00 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
20e10 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
20e20 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
20e30 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
20e40 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
20e50 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
20e60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
20e70 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
20e80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20e90 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
20ea0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
20eb0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
20ec0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
20ed0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
20ee0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
20ef0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
20f00 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
20f10 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
20f20 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
20f30 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
20f40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
20f50 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
20f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
20f70 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
20f80 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
20f90 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
20fa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
20fb0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
20fc0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
20fd0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
20fe0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
20ff0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
21000 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
21010 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
21020 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
21030 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
21040 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
21050 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
21060 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
21070 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
21080 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
21090 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
210a0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
210b0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
210c0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
210d0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
210e0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
210f0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
21100 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
21110 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
21120 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
21130 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
21140 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
21150 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
21160 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
21170 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
21180 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
21190 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
211a0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
211b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
211c0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
211d0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
211e0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
211f0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
21200 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
21210 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
21220 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
21230 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
21240 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
21250 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
21260 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
21270 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
21280 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
21290 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
212a0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
212b0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
212c0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
212d0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
212e0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
212f0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
21300 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
21310 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
21320 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
21330 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
21340 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
21350 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
21360 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
21370 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
21380 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
21390 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
213a0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
213b0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
213c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
213d0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
213e0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
213f0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
21400 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
21410 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
21420 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
21430 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
21440 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
21450 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
21460 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
21470 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
21480 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
21490 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
214a0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
214b0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
214c0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
214d0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
214e0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
214f0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
21500 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
21510 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
21520 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
21530 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
21540 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
21550 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
21560 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21570 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
21580 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
21590 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
215a0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
215b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
215c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
215d0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
215e0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
215f0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
21600 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
21610 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
21620 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
21630 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
21640 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
21650 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
21660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21670 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
21680 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
21690 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
216a0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
216b0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
216c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
216d0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
216e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
216f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
21700 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
21710 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
21720 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
21730 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
21740 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
21750 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
21760 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
21770 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
21780 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
21790 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
217a0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
217b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
217c0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
217d0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
217e0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
217f0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
21800 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21810 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
21820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
21830 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21840 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
21850 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
21860 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
21870 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
21880 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21890 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
218a0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
218b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
218c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
218d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
218e0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
218f0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
21900 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21910 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
21920 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
21930 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
21940 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21950 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
21960 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
21970 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
21980 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
21990 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
219a0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
219b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
219c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
219d0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
219e0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
219f0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
21a00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21a10 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
21a20 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
21a30 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
21a40 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
21a50 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
21a60 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
21a70 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
21a80 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
21a90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21aa0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
21ab0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
21ac0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
21ad0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
21ae0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21af0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
21b00 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
21b10 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
21b20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
21b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
21b40 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
21b50 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
21b60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21b70 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
21b80 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
21b90 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
21ba0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
21bb0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
21bc0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
21bd0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
21be0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
21bf0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
21c00 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
21c10 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
21c20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
21c30 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
21c40 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
21c50 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
21c60 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
21c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
21c80 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
21c90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21ca0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
21cb0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
21cc0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
21cd0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21ce0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
21cf0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
21d00 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
21d10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
21d20 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
21d30 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
21d40 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
21d50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
21d60 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
21d70 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
21d80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
21d90 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
21da0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
21db0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
21dc0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
21dd0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
21de0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
21df0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
21e00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
21e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
21e20 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
21e30 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
21e40 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
21e50 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
21e60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
21e70 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
21e80 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
21e90 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
21ea0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
21eb0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
21ec0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
21ed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
21ee0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
21ef0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
21f00 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
21f10 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
21f20 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
21f30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
21f40 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
21f50 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
21f60 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
21f70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
21f80 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
21f90 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
21fa0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
21fb0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
21fc0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
21fd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
21fe0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
21ff0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
22000 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
22010 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
22020 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
22030 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22040 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
22050 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
22060 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22070 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
22080 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
22090 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
220a0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
220b0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
220c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
220d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
220e0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
220f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22100 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
22110 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
22120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22130 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
22140 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
22150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22160 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
22170 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
22180 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
22190 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
221a0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
221b0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
221c0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
221d0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
221e0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
221f0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
22200 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
22210 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
22220 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
22230 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
22240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22250 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
22260 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
22270 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
22280 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
22290 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
222a0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
222b0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
222c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
222d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
222e0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
222f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
22300 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
22310 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
22320 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
22330 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
22340 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
22350 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
22360 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
22380 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
22390 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
223a0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
223b0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
223c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
223d0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
223e0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
223f0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
22400 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
22410 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
22420 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
22430 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
22440 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
22450 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
22460 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
22470 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
22480 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
22490 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
224a0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
224b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
224c0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
224d0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
224e0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
224f0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
22500 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
22510 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
22520 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
22530 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
22540 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
22550 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
22560 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
22570 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
22580 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
22590 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
225a0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
225b0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
225c0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
225d0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
225e0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
225f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
22600 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
22610 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
22620 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
22630 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
22640 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
22650 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
22660 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
22670 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
22680 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
22690 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
226a0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
226b0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
226c0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
226d0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
226e0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
226f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
22700 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
22710 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
22720 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
22730 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
22740 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
22750 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
22760 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
22770 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
22780 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
22790 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
227a0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
227b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
227c0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
227d0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
227e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
227f0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
22800 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
22810 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
22820 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
22830 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
22840 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
22850 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
22860 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
22870 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
22880 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
22890 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
228a0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
228b0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
228c0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
228d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
228e0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
228f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22900 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
22910 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
22920 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
22930 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
22940 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
22950 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
22960 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
22970 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
22980 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
22990 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
229a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
229b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
229c0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
229d0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
229e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
229f0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
22a00 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
22a10 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
22a20 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
22a30 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
22a40 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
22a50 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
22a60 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
22a70 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
22a80 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
22a90 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
22aa0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
22ab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
22ac0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
22ad0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
22ae0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
22af0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
22b00 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
22b10 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
22b20 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
22b30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
22b40 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
22b50 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
22b60 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
22b70 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
22b80 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
22b90 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
22ba0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
22bb0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
22bc0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
22bd0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
22be0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
22bf0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
22c00 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
22c10 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
22c20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
22c30 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
22c40 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
22c50 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
22c60 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
22c70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22c80 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
22c90 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
22ca0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
22cb0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
22cc0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
22cd0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
22ce0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
22cf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22d00 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
22d10 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
22d20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
22d30 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
22d40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
22d50 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
22d60 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
22d70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
22d80 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
22d90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
22da0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
22db0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
22dc0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
22dd0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
22de0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
22df0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
22e00 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
22e10 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
22e20 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
22e30 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
22e40 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
22e50 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
22e60 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
22e70 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
22e80 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
22e90 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
22ea0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
22eb0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
22ec0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
22ed0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
22ee0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
22ef0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
22f00 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
22f10 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
22f20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
22f30 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
22f40 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
22f50 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
22f60 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
22f70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
22f80 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
22f90 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
22fa0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
22fb0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
22fc0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
22fd0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
22fe0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
22ff0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
23000 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
23010 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
23020 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
23030 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
23040 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
23050 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
23060 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
23070 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
23080 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
23090 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
230a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
230b0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
230c0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
230d0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
230e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
230f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
23100 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
23110 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
23120 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
23130 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
23140 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
23150 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
23160 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
23170 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
23180 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
23190 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
231a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
231b0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
231c0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
231d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
231e0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
231f0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
23200 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
23210 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
23220 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
23230 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
23240 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
23250 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
23260 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
23270 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
23280 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
23290 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
232a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
232b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
232c0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
232d0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
232e0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
232f0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
23300 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
23310 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23320 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
23330 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
23340 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
23350 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
23360 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23370 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
23380 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
23390 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
233a0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
233b0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
233c0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
233d0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
233e0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
233f0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
23400 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
23410 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
23420 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
23430 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
23440 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
23450 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
23460 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
23470 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
23480 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
23490 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
234a0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
234b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
234c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
234d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
234e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
234f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
23500 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
23510 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
23520 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
23530 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
23540 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23550 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
23560 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
23570 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
23580 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
23590 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
235a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
235b0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
235c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
235d0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
235e0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
235f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23600 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
23610 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
23620 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
23630 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
23640 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
23650 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
23660 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
23670 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
23680 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
23690 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
236a0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
236b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
236c0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
236d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
236e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
236f0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
23700 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
23710 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
23720 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23740 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
23750 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
23760 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
23770 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
23780 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
23790 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
237a0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
237b0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
237c0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
237d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
237e0 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
237f0 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
23800 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
23810 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
23820 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
23830 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
23840 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
23850 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
23860 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
23870 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
23880 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
23890 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
238a0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
238b0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
238c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
238d0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
238e0 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
238f0 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
23900 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
23910 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
23920 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
23930 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
23940 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
23950 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
23960 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
23970 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
23980 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
23990 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
239a0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
239b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
239c0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
239d0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
239e0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
239f0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
23a00 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
23a10 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
23a20 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
23a30 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
23a40 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
23a50 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
23a60 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
23a70 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
23a80 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
23a90 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
23aa0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
23ab0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
23ac0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
23ad0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
23ae0 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
23af0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
23b00 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
23b10 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
23b20 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
23b30 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
23b40 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
23b50 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
23b60 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
23b70 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
23b80 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
23b90 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
23ba0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
23bb0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
23bc0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
23bd0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
23be0 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
23bf0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
23c00 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
23c10 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
23c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23c30 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
23c40 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
23c50 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
23c60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23c70 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
23c80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
23c90 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
23ca0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
23cb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23cc0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
23cd0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23ce0 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
23cf0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
23d00 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
23d10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
23d20 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
23d30 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
23d40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23d50 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
23d60 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
23d70 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
23d80 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
23d90 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
23da0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
23db0 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
23dc0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
23dd0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
23de0 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
23df0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
23e00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
23e10 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
23e20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
23e30 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
23e40 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
23e50 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
23e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
23e70 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
23e80 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
23e90 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
23ea0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
23eb0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
23ec0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
23ed0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
23ee0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
23ef0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
23f00 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
23f10 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
23f20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
23f30 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
23f40 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
23f50 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
23f60 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
23f70 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
23f80 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
23f90 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
23fa0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
23fb0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
23fc0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
23fd0 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
23fe0 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
23ff0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
24000 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
24010 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
24030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24040 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
24050 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
24060 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
24070 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24080 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
24090 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
240a0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
240b0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
240c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
240d0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
240e0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
240f0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
24100 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
24110 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
24120 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
24130 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
24140 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
24150 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
24160 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
24170 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
24180 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
24190 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
241a0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
241b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
241c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
241d0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
241e0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
241f0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
24200 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
24210 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
24220 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24230 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
24240 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
24250 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
24260 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
24270 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
24280 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
24290 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
242a0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
242b0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
242c0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
242d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
242e0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
242f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24300 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
24310 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
24320 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
24330 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
24340 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
24350 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
24360 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
24370 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
24380 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
24390 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
243a0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
243b0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
243c0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
243d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
243e0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
243f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
24400 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
24410 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
24420 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
24430 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
24440 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
24450 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
24460 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
24470 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
24480 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
24490 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
244a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
244b0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
244c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
244d0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
244e0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
244f0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
24500 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
24510 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
24520 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
24530 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
24540 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
24550 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
24560 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
24570 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
24580 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
24590 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
245a0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
245b0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
245c0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
245d0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
245e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
245f0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
24600 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
24610 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
24620 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
24630 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
24640 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
24650 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
24660 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
24670 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
24680 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
24690 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
246a0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
246b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
246c0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
246d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
246e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
246f0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
24700 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
24710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24720 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
24730 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
24740 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
24750 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
24760 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
24770 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
24780 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
24790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
247a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
247b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
247c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
247d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
247e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
247f0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
24800 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
24810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
24820 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
24830 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
24840 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
24850 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
24860 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
24870 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
24880 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
24890 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
248a0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
248b0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
248c0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
248d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
248e0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
248f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
24900 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
24910 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
24920 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
24930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
24940 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
24950 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
24960 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
24970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
24980 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
24990 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
249a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
249b0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
249c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
249d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
249e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
249f0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
24a00 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
24a10 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
24a20 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
24a30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24a40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
24a50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
24a60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24a70 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
24a80 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
24a90 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
24aa0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
24ab0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
24ac0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
24ad0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
24ae0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
24af0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
24b00 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
24b10 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
24b20 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
24b30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
24b40 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
24b50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24b60 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
24b70 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
24b80 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
24b90 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
24ba0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
24bb0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
24bc0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
24bd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
24be0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
24bf0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
24c00 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
24c10 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
24c20 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
24c30 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
24c40 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
24c50 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
24c60 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
24c70 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
24c80 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
24c90 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
24ca0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
24cb0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
24cc0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
24cd0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
24ce0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
24cf0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
24d00 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
24d10 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
24d20 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
24d30 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
24d40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
24d50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
24d60 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
24d70 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
24d80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24d90 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
24da0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
24db0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
24dc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24dd0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
24de0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
24df0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
24e00 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
24e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
24e20 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
24e30 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
24e40 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
24e50 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
24e60 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
24e70 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
24e80 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
24e90 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
24ea0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
24eb0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
24ec0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
24ed0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
24ee0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
24ef0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
24f00 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
24f10 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
24f20 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
24f30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24f40 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
24f50 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
24f60 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
24f70 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
24f80 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
24f90 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
24fa0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
24fb0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
24fc0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
24fd0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
24fe0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
24ff0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
25000 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
25010 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
25020 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
25030 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
25040 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
25050 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
25060 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
25070 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
25080 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
25090 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
250a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
250b0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
250c0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
250d0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
250e0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
250f0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
25100 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
25110 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
25120 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
25130 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25140 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
25150 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
25160 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
25170 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
25180 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
25190 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
251a0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e  nator..** If a n
251b0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
251c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
251d0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
251e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
251f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
25200 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
25210 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
25220 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
25230 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
25240 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
25250 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
25260 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
25270 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
25280 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
25290 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
252a0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
252b0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
252c0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
252d0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
252e0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
252f0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
25300 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
25310 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
25320 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
25330 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
25340 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
25350 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
25360 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
25370 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25380 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
25390 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
253a0 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
253b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
253c0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
253d0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
253e0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
253f0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
25400 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
25410 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
25420 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
25430 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
25440 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
25450 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
25460 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
25470 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
25480 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
25490 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
254a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
254b0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
254c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
254d0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
254e0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
254f0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
25500 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
25510 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
25520 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
25530 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
25540 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
25550 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
25560 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
25570 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
25580 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
25590 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
255a0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
255b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
255c0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
255d0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
255e0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
255f0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
25600 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
25610 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
25620 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
25630 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
25640 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
25650 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
25660 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
25670 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
25680 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
25690 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
256a0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
256b0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
256c0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
256d0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
256e0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
256f0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
25700 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
25710 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
25720 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
25730 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
25740 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
25750 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
25760 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
25770 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
25780 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
25790 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
257a0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
257b0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
257c0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
257d0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
257e0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
257f0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
25800 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25810 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
25820 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
25830 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
25840 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25850 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
25860 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25870 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
25880 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25890 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
258a0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
258b0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
258c0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
258d0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
258e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
258f0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
25900 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
25910 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
25920 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
25930 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
25940 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
25950 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
25960 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
25970 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
25980 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
25990 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
259a0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
259b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
259c0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
259d0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
259e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
259f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
25a00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
25a10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
25a20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
25a30 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
25a40 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
25a50 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
25a60 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
25a70 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
25a80 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
25a90 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
25aa0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
25ab0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
25ac0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
25ad0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
25ae0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25af0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25b00 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
25b10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25b20 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
25b30 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
25b40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25b50 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
25b60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
25b70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
25b80 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
25b90 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
25ba0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
25bb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
25bc0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
25bd0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
25be0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
25bf0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
25c00 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
25c10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25c20 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
25c30 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
25c40 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
25c50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
25c60 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
25c70 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
25c80 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
25c90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25ca0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
25cb0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
25cc0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
25cd0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
25ce0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25cf0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
25d00 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
25d10 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
25d20 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
25d30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
25d40 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
25d50 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
25d60 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
25d70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25d80 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
25d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
25da0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
25db0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
25dc0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
25dd0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
25de0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
25df0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
25e00 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
25e10 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
25e20 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
25e30 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
25e40 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
25e50 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
25e60 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
25e70 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
25e80 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
25e90 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
25ea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25eb0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
25ec0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
25ed0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
25ee0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
25ef0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
25f00 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
25f10 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
25f20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
25f30 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
25f40 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
25f50 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
25f60 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
25f70 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
25f80 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
25f90 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
25fa0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
25fb0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
25fc0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
25fd0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
25fe0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25ff0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
26000 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
26010 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
26020 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
26030 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
26040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26050 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
26060 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
26070 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
26080 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
26090 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
260a0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
260b0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
260c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
260d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
260e0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
260f0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
26100 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
26110 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
26120 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
26130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26140 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
26150 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
26160 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
26170 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
26180 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
26190 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
261a0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
261b0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
261c0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
261d0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
261e0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
261f0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
26200 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
26210 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
26220 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
26230 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
26240 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
26250 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
26260 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
26270 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
26280 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
26290 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
262a0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
262b0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
262c0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
262d0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
262e0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
262f0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
26300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
26310 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
26320 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
26330 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
26340 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
26350 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
26360 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
26370 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
26380 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
26390 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
263a0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
263b0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
263c0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
263d0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
263e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
263f0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
26400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26410 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
26420 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
26430 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
26440 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
26450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26460 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
26470 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
26480 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
26490 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
264a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
264b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
264c0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
264d0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
264e0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
264f0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
26500 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
26510 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
26520 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
26530 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
26540 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
26550 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
26560 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
26570 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
26580 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
26590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
265a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
265b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
265c0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
265d0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
265e0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
265f0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
26600 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
26610 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
26620 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
26630 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
26640 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
26650 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
26660 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
26670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26680 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
26690 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
266a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
266b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
266c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
266d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
266e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
266f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26700 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
26710 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26720 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
26730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26740 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
26750 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
26760 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
26770 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
26780 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
26790 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
267a0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
267b0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
267c0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
267d0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
267e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
267f0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
26800 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
26810 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
26820 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
26830 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
26840 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
26850 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
26860 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
26870 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
26880 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
26890 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
268a0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
268b0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
268c0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
268d0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
268e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
268f0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
26900 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26910 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
26920 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
26930 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
26940 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
26950 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
26960 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
26970 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
26980 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
26990 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
269a0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
269b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
269c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
269d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
269e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
269f0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
26a00 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
26a10 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
26a20 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
26a30 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
26a40 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
26a50 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
26a60 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
26a70 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
26a80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
26a90 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
26aa0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26ab0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
26ac0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26ad0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
26ae0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
26af0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
26b00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
26b10 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26b20 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
26b30 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
26b40 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
26b50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26b60 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
26b70 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
26b80 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
26b90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
26ba0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
26bb0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
26bc0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
26bd0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
26be0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
26bf0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
26c00 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
26c10 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
26c20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26c30 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
26c40 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
26c50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
26c60 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
26c70 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
26c80 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
26c90 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
26ca0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26cb0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
26cc0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
26cd0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
26ce0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
26cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26d00 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
26d10 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
26d20 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
26d30 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
26d40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
26d50 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
26d60 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
26d70 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
26d80 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
26d90 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
26da0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
26db0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
26dc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
26dd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26de0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
26df0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
26e00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
26e10 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
26e20 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
26e30 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
26e40 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
26e50 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
26e60 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
26e70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
26e80 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
26e90 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
26ea0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
26eb0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
26ec0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
26ed0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
26ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
26ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26f00 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
26f10 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
26f20 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
26f30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
26f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26f50 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
26f60 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
26f70 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
26f80 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
26f90 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
26fa0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
26fb0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
26fc0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
26fd0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
26fe0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
26ff0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
27000 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
27010 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
27020 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
27030 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
27040 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
27050 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
27060 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
27070 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
27080 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
27090 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
270a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
270b0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
270c0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
270d0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
270e0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
270f0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
27100 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
27110 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
27120 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
27130 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
27140 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27150 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
27160 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
27170 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27180 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
27190 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
271a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
271b0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
271c0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
271d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
271e0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
271f0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
27200 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
27210 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
27220 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
27230 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
27240 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
27250 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
27260 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
27270 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
27280 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
27290 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
272a0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
272b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
272c0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
272d0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
272e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
272f0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
27300 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
27310 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
27320 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
27330 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
27340 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
27350 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
27360 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
27370 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
27380 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
27390 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
273a0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
273b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
273c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
273d0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
273e0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
273f0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
27400 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
27410 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
27420 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
27430 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
27440 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
27450 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
27460 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
27470 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
27480 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
27490 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
274a0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
274b0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
274c0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
274d0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
274e0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
274f0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
27500 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
27510 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
27520 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
27530 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
27540 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
27550 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
27560 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
27570 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
27580 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
27590 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
275a0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
275b0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
275c0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
275d0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
275e0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
275f0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
27600 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
27610 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
27620 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
27630 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
27640 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
27650 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
27660 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
27670 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
27680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27690 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
276a0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
276b0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
276c0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
276d0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
276e0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
276f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
27700 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27710 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
27720 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
27730 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
27740 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
27750 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27760 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
27770 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
27780 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
27790 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
277a0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
277b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
277c0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
277d0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
277e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
277f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
27800 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
27810 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27820 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
27830 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27840 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
27850 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
27860 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
27880 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
27890 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
278a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
278b0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
278c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
278d0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
278e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
278f0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
27900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
27910 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27920 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
27930 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
27940 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
27950 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
27960 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
27970 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
27980 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
27990 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
279a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
279b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
279c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
279d0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
279e0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
279f0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
27a00 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
27a10 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
27a20 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
27a30 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
27a40 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
27a50 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
27a60 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
27a70 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
27a80 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
27a90 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
27aa0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
27ab0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
27ac0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
27ad0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
27ae0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
27af0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
27b00 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
27b10 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
27b20 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
27b30 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
27b40 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
27b50 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
27b60 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
27b70 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
27b80 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
27b90 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
27ba0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
27bb0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
27bc0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
27bd0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
27be0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
27bf0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
27c00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27c10 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
27c20 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
27c30 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
27c40 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
27c50 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
27c60 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
27c70 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
27c80 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
27c90 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
27ca0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
27cb0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
27cc0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
27cd0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
27ce0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
27cf0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
27d00 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
27d10 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
27d20 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
27d30 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
27d40 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
27d50 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
27d60 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
27d70 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
27d80 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
27d90 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
27da0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
27db0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27dc0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
27dd0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
27de0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27df0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
27e00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27e10 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27e20 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
27e30 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
27e40 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
27e50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27e60 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
27e70 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
27e80 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
27e90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27ea0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27eb0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
27ec0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
27ed0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
27ee0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
27ef0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27f00 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
27f10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
27f20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
27f30 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
27f40 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
27f50 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
27f60 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
27f70 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
27f80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
27f90 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
27fa0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
27fb0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
27fc0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
27fd0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
27fe0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
27ff0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28000 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
28010 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
28020 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
28030 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
28040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28050 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28060 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
28070 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
28080 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
28090 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
280a0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
280b0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
280c0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
280d0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
280e0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
280f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
28100 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
28110 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
28120 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
28130 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
28140 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
28150 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
28160 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
28170 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
28180 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
28190 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
281a0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
281b0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
281c0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
281d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
281e0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
281f0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
28200 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
28210 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
28220 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
28230 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
28240 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
28250 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
28260 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
28270 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
28280 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
28290 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
282a0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
282b0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
282c0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
282d0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
282e0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
282f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
28300 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
28310 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
28320 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
28330 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
28340 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
28350 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
28360 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
28370 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
28380 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
28390 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
283a0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
283b0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
283c0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
283d0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
283e0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
283f0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
28400 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
28410 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
28420 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
28430 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28440 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
28450 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
28460 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
28470 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
28480 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
28490 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
284a0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
284b0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
284c0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
284d0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
284e0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
284f0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
28500 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
28510 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
28520 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
28530 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
28540 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
28550 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
28560 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
28570 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
28580 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
28590 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
285a0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
285b0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
285c0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
285d0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
285e0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
285f0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
28600 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
28610 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
28620 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
28630 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
28640 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
28650 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
28660 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
28670 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
28680 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
28690 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
286a0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
286b0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
286c0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
286d0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
286e0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
286f0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
28700 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
28710 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
28720 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
28730 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
28740 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
28750 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
28760 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
28770 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
28780 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
28790 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
287a0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
287b0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
287c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
287d0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
287e0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
287f0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
28800 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
28810 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
28820 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
28830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
28840 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
28850 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
28860 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
28870 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
28880 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
28890 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
288a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
288b0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
288c0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
288d0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
288e0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
288f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
28900 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
28910 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
28920 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
28930 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
28940 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
28950 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
28960 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
28970 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
28980 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
28990 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
289a0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
289b0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
289c0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
289d0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
289e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
289f0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
28a00 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
28a10 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
28a20 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
28a30 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
28a40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28a50 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
28a60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
28a70 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
28a80 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
28a90 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
28aa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
28ab0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
28ac0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
28ad0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
28ae0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
28af0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
28b00 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
28b10 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
28b20 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
28b30 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
28b40 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
28b50 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
28b60 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
28b70 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
28b80 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
28b90 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
28ba0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
28bb0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
28bc0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
28bd0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
28be0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
28bf0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
28c00 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
28c10 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
28c20 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
28c30 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
28c40 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
28c50 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
28c60 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
28c70 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
28c80 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
28c90 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
28ca0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
28cb0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
28cc0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
28cd0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
28ce0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
28cf0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
28d00 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
28d10 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
28d20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
28d30 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
28d40 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
28d50 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
28d60 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
28d70 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
28d80 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
28d90 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
28da0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
28db0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
28dc0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
28dd0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
28de0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
28df0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
28e00 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
28e10 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
28e20 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
28e30 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
28e40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28e50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
28e60 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
28e70 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
28e80 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
28e90 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
28ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28eb0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
28ec0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
28ed0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
28ee0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
28ef0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
28f00 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
28f10 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
28f20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
28f30 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
28f40 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
28f50 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
28f60 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
28f70 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
28f80 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
28f90 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
28fa0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
28fb0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
28fc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28fd0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28fe0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
28ff0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
29000 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
29010 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29020 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
29030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29040 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
29050 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
29060 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
29070 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
29080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
29090 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
290a0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
290b0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
290c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
290d0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
290e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
290f0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
29100 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
29110 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
29120 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
29130 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29140 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
29150 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
29160 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
29170 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
29180 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
29190 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
291a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
291b0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
291c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
291d0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
291e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
291f0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
29200 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
29210 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
29220 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
29230 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
29240 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
29250 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
29260 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
29270 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
29280 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
29290 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
292a0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
292b0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
292c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
292d0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
292e0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
292f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
29300 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
29310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
29320 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
29330 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
29340 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
29350 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
29360 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
29370 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
29380 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
29390 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
293a0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
293b0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
293c0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
293d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
293e0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
293f0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
29400 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
29410 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
29420 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
29430 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
29440 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
29450 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
29460 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
29470 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
29480 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
29490 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
294a0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
294b0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
294c0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
294d0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
294e0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
294f0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
29500 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
29510 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
29520 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
29530 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
29540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
29550 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
29560 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
29570 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
29580 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
29590 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
295a0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
295b0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
295c0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
295d0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
295e0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
295f0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
29600 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
29610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29620 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
29630 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
29640 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
29650 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
29660 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
29670 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
29680 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
29690 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
296a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
296b0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
296c0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
296d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
296e0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
296f0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
29700 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
29710 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
29720 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
29730 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
29740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29750 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
29760 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
29770 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
29780 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
29790 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
297a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
297b0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
297c0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
297d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
297e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
297f0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
29800 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
29810 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
29820 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
29830 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
29840 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29850 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
29860 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
29870 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
29880 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
29890 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
298a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
298b0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
298c0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
298d0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
298e0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
298f0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
29900 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
29910 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
29920 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
29930 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
29940 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
29950 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
29960 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
29970 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29980 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
29990 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
299a0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
299b0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
299c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
299d0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
299e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
299f0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
29a00 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
29a10 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
29a20 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
29a30 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
29a40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
29a50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
29a60 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
29a70 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
29a80 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
29a90 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
29aa0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
29ab0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
29ac0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
29ad0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
29ae0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
29af0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
29b00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
29b10 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
29b20 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
29b30 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
29b40 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
29b50 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
29b60 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
29b70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
29b80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
29b90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29ba0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
29bb0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
29bc0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
29bd0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
29be0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
29bf0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
29c00 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
29c10 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
29c20 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
29c30 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
29c40 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
29c50 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
29c60 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
29c70 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
29c80 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
29c90 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
29ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29cb0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
29cc0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
29cd0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
29ce0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
29cf0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
29d00 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
29d10 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
29d20 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
29d30 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
29d40 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
29d50 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
29d60 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
29d70 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
29d80 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
29d90 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
29da0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
29db0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
29dc0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
29dd0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
29de0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
29df0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
29e00 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
29e10 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
29e20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
29e30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
29e40 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
29e50 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
29e60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
29e70 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
29e80 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
29e90 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
29ea0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
29eb0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
29ec0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
29ed0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29ee0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
29ef0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
29f00 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
29f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29f20 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
29f30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
29f40 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
29f50 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
29f60 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
29f70 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
29f80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
29f90 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
29fa0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
29fb0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
29fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29fd0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
29fe0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
29ff0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2a000 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2a010 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2a020 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a030 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2a040 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2a050 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2a060 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2a070 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2a080 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2a090 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2a0a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a0b0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2a0c0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2a0d0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2a0e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2a0f0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2a100 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2a110 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2a120 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2a130 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2a140 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2a150 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2a160 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2a170 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2a180 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2a190 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2a1a0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2a1b0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2a1c0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2a1d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2a1e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2a1f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2a200 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2a210 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2a220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a230 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2a240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a250 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2a260 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2a270 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2a280 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2a290 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2a2a0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2a2b0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2a2c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a2d0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2a2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a2f0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2a300 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2a310 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2a320 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2a330 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2a340 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2a350 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2a360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a370 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2a380 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2a390 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2a3a0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2a3b0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2a3c0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2a3d0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2a3e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2a3f0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2a400 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2a410 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2a420 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2a430 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2a440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2a450 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2a460 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a470 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a480 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2a490 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2a4a0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2a4b0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2a4c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2a4d0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2a4e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2a4f0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2a500 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a510 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a520 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2a530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a540 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2a550 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2a560 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2a570 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2a580 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2a590 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2a5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a5b0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2a5c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2a5d0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2a5e0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2a5f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2a600 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2a610 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2a620 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2a630 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2a640 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2a650 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2a660 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2a670 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2a680 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2a690 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2a6a0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2a6b0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2a6c0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2a6d0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2a6e0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2a6f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2a700 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2a710 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2a720 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2a730 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2a740 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2a750 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2a760 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2a770 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2a780 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2a790 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2a7a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2a7b0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2a7c0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2a7d0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2a7e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2a7f0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2a800 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2a810 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2a820 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2a830 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2a840 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2a850 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2a860 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2a870 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2a880 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2a890 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2a8a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2a8b0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2a8c0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2a8d0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2a8e0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2a8f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2a900 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2a910 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2a920 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2a930 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2a940 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2a950 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2a960 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2a970 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2a980 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2a990 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2a9a0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2a9b0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2a9c0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2a9d0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2a9e0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2a9f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2aa00 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2aa10 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2aa20 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2aa30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2aa40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2aa50 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2aa60 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2aa70 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2aa80 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2aa90 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2aaa0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2aab0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2aac0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2aad0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2aae0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2aaf0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2ab00 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2ab10 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2ab20 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2ab30 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2ab40 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2ab50 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2ab60 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2ab70 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2ab80 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2ab90 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2aba0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2abb0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2abc0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2abd0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2abe0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2abf0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2ac00 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2ac10 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2ac20 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2ac30 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2ac40 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2ac50 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2ac60 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2ac70 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2ac80 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2ac90 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2aca0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2acb0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2acc0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2acd0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2ace0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2acf0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2ad00 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2ad10 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2ad20 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2ad30 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2ad40 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2ad50 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2ad60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2ad70 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2ad80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ad90 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2ada0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2adb0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2adc0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2add0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2ade0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2adf0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2ae00 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2ae10 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2ae20 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2ae30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ae40 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2ae50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ae60 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2ae70 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2ae80 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2ae90 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2aea0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2aeb0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2aec0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2aed0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2aee0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2aef0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2af00 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2af10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2af20 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2af30 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2af40 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2af50 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2af60 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2af70 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2af80 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2af90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2afa0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2afb0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2afc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2afd0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2afe0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2aff0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2b000 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2b010 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2b020 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2b030 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2b040 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2b050 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2b060 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2b070 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2b080 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2b090 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2b0a0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2b0b0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2b0c0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2b0d0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2b0e0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2b0f0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2b100 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2b110 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2b120 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2b130 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2b140 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2b150 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2b160 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2b170 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2b180 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2b190 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2b1a0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2b1b0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2b1c0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2b1d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2b1e0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2b1f0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2b200 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2b210 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2b220 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2b230 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2b240 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2b250 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2b260 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2b270 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2b280 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2b290 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2b2a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b2b0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2b2c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2b2d0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2b2e0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2b2f0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2b300 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2b310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b320 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2b330 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2b340 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2b350 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2b360 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2b370 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2b380 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2b390 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2b3a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b3b0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2b3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b3d0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2b3e0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2b3f0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2b400 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2b410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2b420 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2b430 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2b440 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2b450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b460 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2b470 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2b480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b490 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2b4a0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b4b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2b4c0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2b4d0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2b4e0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2b4f0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2b500 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2b510 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2b520 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2b530 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2b540 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2b550 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b560 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2b570 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2b580 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2b590 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2b5a0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2b5b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2b5c0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2b5d0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2b5e0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2b5f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2b600 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2b610 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2b620 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2b630 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2b640 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2b650 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2b660 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2b670 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2b680 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2b690 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2b6a0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2b6b0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2b6c0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2b6d0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2b6e0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2b6f0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2b700 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2b710 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2b720 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2b730 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2b740 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2b750 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2b760 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2b770 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b780 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2b790 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b7a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2b7b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2b7c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2b7d0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2b7e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b7f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b800 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2b810 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2b820 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2b830 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b840 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2b850 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2b860 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b870 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2b880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b890 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2b8a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b8b0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2b8c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b8d0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2b8e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b8f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b910 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2b920 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2b930 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2b940 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2b950 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2b960 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2b970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2b980 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2b990 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2b9a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b9b0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2b9c0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2b9d0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2b9e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b9f0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2ba00 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2ba10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ba20 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2ba30 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2ba40 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2ba50 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2ba60 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2ba70 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2ba80 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2ba90 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2baa0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2bab0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2bac0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2bad0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2bae0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2baf0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2bb00 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2bb10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2bb20 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2bb30 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2bb40 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2bb50 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2bb60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2bb70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2bb80 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2bb90 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2bba0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2bbb0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2bbc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bbd0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2bbe0 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2bbf0 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2bc00 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2bc10 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2bc20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bc30 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2bc40 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2bc50 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2bc60 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2bc70 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2bc80 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2bc90 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2bca0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2bcb0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2bcc0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2bcd0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2bce0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2bcf0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2bd00 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2bd10 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2bd20 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2bd30 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2bd40 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2bd50 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2bd60 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2bd70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2bd80 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2bd90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bda0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2bdb0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2bdc0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2bdd0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2bde0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2bdf0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2be00 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2be10 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2be20 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2be30 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2be40 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2be50 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
2be60 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2be70 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2be80 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2be90 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2bea0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2beb0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2bec0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2bed0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2bee0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2bef0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2bf00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2bf10 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2bf20 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2bf30 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2bf40 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2bf50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2bf60 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2bf70 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2bf80 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2bf90 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2bfa0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2bfb0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2bfc0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2bfd0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2bfe0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2bff0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2c000 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2c010 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2c020 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2c030 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2c040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c050 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2c060 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2c070 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2c080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2c090 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2c0a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2c0b0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2c0c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c0d0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2c0e0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2c0f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2c100 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2c110 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2c120 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2c130 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2c140 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2c150 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2c160 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2c170 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2c180 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2c190 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2c1a0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2c1b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2c1c0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2c1d0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2c1e0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2c1f0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2c200 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2c210 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2c220 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2c230 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2c240 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2c250 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2c260 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c270 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2c280 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c290 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2c2a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2c2b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2c2c0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2c2d0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2c2e0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2c2f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2c300 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2c310 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2c320 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2c330 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2c340 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c350 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2c360 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2c370 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c380 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2c390 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2c3a0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2c3b0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2c3c0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2c3d0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2c3e0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2c3f0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2c400 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2c410 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2c420 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2c430 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2c440 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2c450 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2c460 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2c470 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2c480 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2c490 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2c4a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2c4b0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2c4c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2c4d0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2c4e0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2c4f0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2c500 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2c510 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2c520 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2c530 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2c540 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2c550 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2c560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2c570 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2c580 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2c590 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2c5a0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2c5b0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2c5c0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2c5d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2c5e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c5f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c600 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2c610 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2c620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c630 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2c640 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2c650 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2c660 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2c670 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2c680 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2c690 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2c6a0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2c6b0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2c6c0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2c6d0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2c6e0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2c6f0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2c700 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2c710 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2c720 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2c730 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2c740 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2c750 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2c760 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2c770 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2c780 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2c790 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2c7a0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2c7b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2c7c0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2c7d0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2c7e0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2c7f0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2c800 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2c810 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2c820 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2c830 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2c840 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2c850 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2c860 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2c870 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2c880 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2c890 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2c8a0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2c8b0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2c8c0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2c8d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2c8e0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2c8f0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2c900 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2c910 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2c920 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2c930 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2c940 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2c950 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2c960 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2c970 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2c980 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2c990 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2c9a0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2c9b0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2c9c0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2c9d0 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2c9e0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2c9f0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2ca00 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2ca10 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2ca20 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2ca30 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2ca40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2ca50 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2ca60 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2ca70 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2ca80 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2ca90 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2caa0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2cab0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2cac0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2cad0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2cae0 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2caf0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2cb00 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2cb10 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2cb20 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2cb30 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2cb40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2cb50 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2cb60 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2cb70 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2cb80 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2cb90 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2cba0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2cbb0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2cbc0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2cbd0 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2cbe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2cbf0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2cc00 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2cc10 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2cc20 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2cc30 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2cc40 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2cc50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2cc60 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2cc70 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2cc80 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2cc90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2cca0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2ccb0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2ccc0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2ccd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2cce0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2ccf0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2cd00 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2cd10 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2cd20 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2cd30 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2cd40 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2cd50 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2cd60 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2cd70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2cd80 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2cd90 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2cda0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2cdb0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2cdc0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2cdd0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2cde0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2cdf0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2ce00 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2ce10 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2ce20 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2ce30 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2ce40 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2ce50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2ce60 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2ce70 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2ce80 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2ce90 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2cea0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2ceb0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2cec0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2ced0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2cee0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2cef0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2cf00 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2cf10 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2cf20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2cf30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cf40 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2cf50 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2cf60 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2cf70 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2cf80 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2cf90 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2cfa0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2cfb0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2cfc0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2cfd0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2cfe0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2cff0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2d000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2d010 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2d020 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2d030 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2d040 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2d050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d060 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2d070 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2d080 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2d090 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2d0a0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2d0b0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2d0c0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2d0d0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2d0e0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2d0f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2d100 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2d110 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2d120 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2d130 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d140 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2d150 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2d160 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2d170 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2d180 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2d190 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2d1a0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2d1b0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2d1c0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2d1d0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2d1e0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2d1f0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2d200 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2d210 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2d220 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d230 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2d240 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2d250 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2d260 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2d270 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2d280 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2d290 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2d2a0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2d2b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2d2c0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2d2d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2d2e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2d2f0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2d300 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2d310 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2d320 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2d330 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2d340 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2d350 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2d360 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2d370 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2d380 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2d390 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2d3a0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2d3b0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2d3c0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2d3d0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2d3e0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2d3f0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2d400 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2d410 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2d420 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2d430 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2d440 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2d450 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
2d460 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2d470 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2d480 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d490 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
2d4a0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
2d4b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2d4c0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
2d4d0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
2d4e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2d4f0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
2d500 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
2d510 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
2d520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d530 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
2d540 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
2d550 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d560 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
2d570 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2d580 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
2d590 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d5a0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2d5b0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2d5c0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2d5d0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2d5e0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2d5f0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2d600 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2d610 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2d620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2d630 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2d640 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2d650 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2d660 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2d670 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2d680 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2d690 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2d6a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2d6b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2d6c0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2d6d0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2d6e0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2d6f0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2d700 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2d710 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2d720 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2d730 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2d740 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2d750 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2d760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2d770 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2d780 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2d790 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
2d7a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d7b0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2d7c0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2d7d0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2d7e0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2d7f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2d800 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2d810 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2d820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2d830 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2d840 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2d850 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2d860 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2d870 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2d880 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2d890 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
2d8a0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2d8b0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
2d8c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2d8d0 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
2d8e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2d8f0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2d900 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2d910 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2d920 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2d930 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2d940 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2d950 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2d960 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2d970 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2d980 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2d990 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2d9a0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2d9b0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2d9c0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2d9d0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2d9e0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2d9f0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2da00 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2da10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2da20 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2da30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2da40 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2da50 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2da60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2da70 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2da80 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
2da90 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
2daa0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
2dab0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2dac0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
2dad0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
2dae0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
2daf0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2db00 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
2db10 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
2db20 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
2db30 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
2db40 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
2db50 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
2db60 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2db70 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2db80 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2db90 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2dba0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2dbb0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2dbc0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2dbd0 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2dbe0 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
2dbf0 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2dc00 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
2dc10 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
2dc20 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2dc30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2dc40 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2dc50 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2dc60 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2dc70 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2dc80 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2dc90 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2dca0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2dcb0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2dcc0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2dcd0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2dce0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2dcf0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2dd00 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2dd10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2dd20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2dd30 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2dd40 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2dd50 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2dd60 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2dd70 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2dd80 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2dd90 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2dda0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
2ddb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2ddc0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
2ddd0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
2dde0 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
2ddf0 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2de00 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2de10 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2de20 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2de30 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2de40 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2de50 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2de60 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2de70 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2de80 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2de90 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2dea0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2deb0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2dec0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2ded0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2dee0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2def0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2df00 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2df10 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2df20 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2df30 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2df40 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2df50 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2df60 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
2df70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2df80 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2df90 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2dfa0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2dfb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dfc0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2dfd0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2dfe0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2dff0 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2e000 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2e010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2e020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e030 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2e040 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2e050 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2e060 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2e070 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e080 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2e090 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2e0a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e0b0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2e0c0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2e0d0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2e0e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2e0f0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2e100 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2e110 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2e120 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
2e130 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2e140 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
2e150 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
2e160 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2e170 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
2e180 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
2e190 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
2e1a0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
2e1b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e1c0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
2e1d0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
2e1e0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
2e1f0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
2e200 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
2e210 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e220 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e230 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
2e240 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
2e250 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2e260 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2e270 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2e280 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
2e290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2e2a0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
2e2b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e2c0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
2e2d0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
2e2e0 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
2e2f0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
2e300 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
2e310 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
2e320 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
2e330 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2e340 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2e350 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
2e360 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
2e370 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
2e380 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
2e390 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
2e3a0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
2e3b0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
2e3c0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
2e3d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
2e3e0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
2e3f0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
2e400 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
2e410 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
2e420 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
2e430 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
2e440 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2e450 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2e460 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2e470 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2e480 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
2e490 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
2e4a0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
2e4b0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
2e4c0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
2e4d0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
2e4e0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
2e4f0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
2e500 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
2e510 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
2e520 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
2e530 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
2e540 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
2e550 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
2e560 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2e570 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2e580 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2e590 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
2e5a0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
2e5b0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
2e5c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e5d0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
2e5e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2e5f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2e600 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2e610 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2e620 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
2e630 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e640 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2e650 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2e660 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2e670 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2e680 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2e690 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2e6a0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
2e6b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e6c0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2e6d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e6e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2e6f0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
2e700 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2e710 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2e720 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e730 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2e740 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
2e750 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2e760 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2e770 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
2e780 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
2e790 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2e7a0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2e7b0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
2e7c0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2e7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e7e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e7f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2e800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e810 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2e820 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2e830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e840 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
2e850 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2e860 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2e870 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
2e880 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2e890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2e8a0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2e8b0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2e8c0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2e8d0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2e8e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e8f0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2e900 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2e910 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
2e920 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2e930 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2e940 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2e950 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
2e960 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
2e970 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2e980 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
2e990 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2e9a0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2e9b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2e9c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2e9d0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
2e9e0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2e9f0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
2ea00 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
2ea10 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
2ea20 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
2ea30 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2ea40 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2ea50 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
2ea60 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
2ea70 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2ea80 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2ea90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2eaa0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2eab0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2eac0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
2ead0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2eae0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
2eaf0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2eb00 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
2eb10 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
2eb20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
2eb30 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
2eb40 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
2eb50 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
2eb60 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
2eb70 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
2eb80 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
2eb90 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
2eba0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
2ebb0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
2ebc0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
2ebd0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2ebe0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
2ebf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
2ec00 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
2ec10 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
2ec20 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
2ec30 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
2ec40 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
2ec50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2ec60 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
2ec70 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
2ec80 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
2ec90 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
2eca0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ecb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2ecc0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
2ecd0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2ece0 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
2ecf0 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
2ed00 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
2ed10 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2ed20 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
2ed30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
2ed40 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
2ed50 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
2ed60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2ed70 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
2ed80 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2ed90 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
2eda0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
2edb0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
2edc0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
2edd0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
2ede0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2edf0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ee00 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
2ee10 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2ee20 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2ee30 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
2ee40 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
2ee50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
2ee60 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2ee70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2ee80 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
2ee90 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
2eea0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2eeb0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
2eec0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
2eed0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2eee0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2eef0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2ef00 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
2ef10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2ef20 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
2ef30 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
2ef40 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
2ef50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
2ef60 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
2ef70 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
2ef80 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
2ef90 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
2efa0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
2efb0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2efc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2efd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2efe0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2eff0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2f000 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2f010 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2f020 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2f030 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2f040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2f050 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2f060 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2f070 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2f080 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2f090 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f0a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f0b0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2f0c0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2f0d0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2f0e0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2f0f0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2f100 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2f110 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f120 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2f130 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f140 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2f150 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2f160 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2f170 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2f180 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2f190 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2f1a0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2f1b0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2f1c0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2f1d0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2f1e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f1f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2f200 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2f210 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2f220 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f230 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f240 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2f250 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
2f260 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2f270 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2f280 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2f290 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f2a0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2f2b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2f2c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f2d0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2f2e0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2f2f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2f300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2f310 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2f320 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f330 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2f340 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2f350 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2f360 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2f370 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
2f380 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2f390 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2f3a0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2f3b0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2f3c0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2f3d0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
2f3e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2f3f0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2f400 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2f410 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2f420 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2f430 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
2f440 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2f450 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2f460 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2f470 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2f480 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2f490 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2f4a0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2f4b0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2f4c0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2f4d0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2f4e0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
2f4f0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
2f500 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
2f510 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
2f520 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
2f530 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
2f540 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
2f550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
2f560 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
2f570 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
2f580 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
2f590 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
2f5a0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2f5b0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2f5c0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2f5d0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2f5e0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
2f5f0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
2f600 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2f610 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
2f620 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
2f630 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2f640 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2f650 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
2f660 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
2f670 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
2f680 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
2f690 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
2f6a0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2f6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2f6c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2f6d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f6e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
2f6f0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
2f700 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
2f710 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f720 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
2f730 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2f740 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
2f750 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f760 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
2f770 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
2f780 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
2f790 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2f7a0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
2f7b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
2f7c0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
2f7d0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
2f7e0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
2f7f0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
2f800 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
2f810 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
2f820 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2f830 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
2f840 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2f850 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2f860 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2f870 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2f880 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
2f890 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
2f8a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
2f8b0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
2f8c0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
2f8d0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
2f8e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f8f0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
2f900 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2f910 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
2f920 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
2f930 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
2f940 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
2f950 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
2f960 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
2f970 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
2f980 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2f990 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
2f9a0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2f9b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2f9c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2f9d0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2f9e0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
2f9f0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2fa00 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2fa10 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2fa20 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2fa30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2fa40 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2fa50 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2fa60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2fa70 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2fa80 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2fa90 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
2faa0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
2fab0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2fac0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
2fad0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2fae0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
2faf0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2fb00 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2fb10 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2fb20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
2fb30 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
2fb40 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
2fb50 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2fb60 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2fb70 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2fb80 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2fb90 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2fba0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2fbb0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2fbc0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
2fbd0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
2fbe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2fbf0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2fc00 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2fc10 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2fc20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2fc30 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2fc40 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
2fc50 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2fc60 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
2fc70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
2fc80 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2fc90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2fca0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
2fcb0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
2fcc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2fcd0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
2fce0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
2fcf0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
2fd00 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2fd10 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
2fd20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2fd30 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2fd40 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2fd50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2fd60 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2fd70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2fd80 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
2fd90 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2fda0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2fdb0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2fdc0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2fdd0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2fde0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2fdf0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2fe00 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2fe10 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2fe20 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
2fe30 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2fe40 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2fe50 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2fe60 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2fe70 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2fe80 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2fe90 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2fea0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2feb0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2fec0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2fed0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2fee0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2fef0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2ff00 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2ff10 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2ff20 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2ff30 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2ff40 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2ff50 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2ff60 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2ff70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2ff80 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2ff90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2ffa0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2ffb0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ffc0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2ffd0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2ffe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fff0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
30000 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
30010 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
30020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30030 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
30040 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
30050 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
30060 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
30070 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
30080 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
30090 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
300a0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
300b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
300c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
300d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
300e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
300f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30100 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
30110 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
30120 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
30130 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
30140 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
30150 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
30160 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
30170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30180 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
30190 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
301a0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
301b0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
301c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
301d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
301e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
301f0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30200 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
30210 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
30220 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30230 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
30240 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
30250 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
30260 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
30270 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
30280 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
30290 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
302a0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
302b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
302c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
302d0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
302e0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
302f0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
30300 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30310 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30320 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
30330 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
30340 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
30350 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
30360 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
30370 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30380 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
303a0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
303b0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
303c0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
303d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
303e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
303f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30400 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
30410 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
30420 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
30430 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30440 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
30450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30460 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
30470 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
30480 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
30490 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
304a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
304b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
304c0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
304d0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
304e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
304f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30500 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
30510 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30520 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
30530 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
30540 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
30550 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
30560 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
30570 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
30580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30590 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
305a0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
305b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
305c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
305d0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
305e0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
305f0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
30600 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
30610 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
30620 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
30630 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
30640 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
30650 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
30660 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
30670 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
30680 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
30690 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
306a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
306b0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
306c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
306d0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
306e0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
306f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30700 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
30710 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
30720 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
30730 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
30740 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
30750 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
30760 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
30770 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
30780 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30790 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
307a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
307b0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
307c0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
307d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
307e0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
307f0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
30800 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
30810 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
30820 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
30830 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
30840 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
30850 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
30860 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
30870 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30880 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
30890 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
308a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
308b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
308c0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
308d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
308e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
308f0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
30900 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
30910 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
30920 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
30930 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
30940 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
30950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30960 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
30970 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
30980 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
30990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
309a0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
309b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
309c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
309d0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
309e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
309f0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
30a00 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
30a10 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
30a20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30a30 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
30a40 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
30a50 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
30a60 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
30a70 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
30a80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
30a90 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
30aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ab0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
30ac0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
30ad0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
30ae0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30af0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30b00 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
30b10 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
30b20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
30b30 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
30b40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30b50 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
30b60 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
30b70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
30b80 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
30b90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30ba0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
30bb0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
30bc0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
30bd0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
30be0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30bf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30c00 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
30c10 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
30c20 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
30c30 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
30c40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30c50 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
30c60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30c70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
30c80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30c90 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
30ca0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30cb0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
30cc0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30cd0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
30ce0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
30cf0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
30d00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30d10 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30d20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
30d30 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
30d40 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
30d50 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
30d60 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
30d70 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
30d80 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
30d90 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
30da0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
30db0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
30dc0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
30dd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30de0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
30df0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
30e00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30e10 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
30e20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
30e30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
30e40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30e50 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
30e60 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
30e70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
30e80 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
30e90 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
30ea0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
30eb0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
30ec0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
30ed0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
30ee0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30ef0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30f00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
30f10 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
30f20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
30f30 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
30f40 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
30f50 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
30f60 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30f70 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
30f80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30f90 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
30fa0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
30fb0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
30fc0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
30fd0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
30fe0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
30ff0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
31000 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
31010 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
31020 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
31030 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
31040 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
31050 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
31060 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
31070 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
31080 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
31090 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
310a0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
310b0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
310c0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
310d0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
310e0 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
310f0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
31100 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
31110 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
31120 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
31130 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
31140 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
31150 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
31160 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
31170 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31180 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
31190 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
311a0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
311b0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
311c0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
311d0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
311e0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
311f0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
31200 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
31210 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
31220 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
31230 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
31240 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
31250 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31270 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
31280 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
31290 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
312a0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
312b0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
312c0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
312d0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
312e0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
312f0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
31300 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
31310 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
31320 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
31330 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
31340 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
31350 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
31360 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
31370 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
31380 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
31390 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
313a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
313b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
313c0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
313d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
313e0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
313f0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
31400 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
31410 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
31420 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
31430 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
31440 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
31450 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
31460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
31470 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
31480 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31490 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
314a0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
314b0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
314c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
314d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
314e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
314f0 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
31500 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31510 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
31520 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
31530 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
31540 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
31550 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
31560 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
31570 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
31580 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
31590 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
315a0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
315b0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
315c0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
315d0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
315e0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
315f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
31600 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
31610 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
31620 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31630 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
31640 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
31650 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
31660 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31670 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31680 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
31690 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
316a0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
316b0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
316c0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
316d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
316e0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
316f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
31700 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
31710 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
31720 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
31730 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
31740 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31750 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
31760 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
31770 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
31780 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
31790 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
317a0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
317b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
317c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
317d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
317e0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
317f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
31800 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
31810 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31820 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
31830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31840 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
31850 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
31860 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
31870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31880 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
31890 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
318a0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
318b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
318c0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
318d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
318e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
318f0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
31900 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31910 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31920 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
31930 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31940 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
31950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31960 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
31970 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
31980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31990 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
319a0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
319b0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
319c0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
319d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
319e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
319f0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
31a00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31a10 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
31a20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31a30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31a40 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
31a50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31a60 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
31a70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31a80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31a90 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
31aa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31ab0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
31ac0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31ad0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31ae0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
31af0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31b00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
31b10 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
31b20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31b30 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
31b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
31b50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
31b60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31b70 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
31b80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
31b90 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
31ba0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
31bb0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
31bc0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
31bd0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
31be0 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
31bf0 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
31c00 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
31c10 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
31c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
31c30 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
31c40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
31c50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
31c60 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
31c70 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
31c80 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
31c90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31ca0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
31cb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31cc0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
31cd0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
31ce0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
31cf0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
31d00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
31d10 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
31d20 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
31d30 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
31d40 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
31d50 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
31d60 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
31d70 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
31d80 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
31d90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
31da0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
31db0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
31dc0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
31dd0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
31de0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
31df0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
31e00 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
31e10 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
31e20 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
31e30 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
31e40 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
31e50 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
31e60 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
31e70 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
31e80 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
31e90 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
31ea0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
31eb0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31ec0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
31ed0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
31ee0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
31ef0 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
31f00 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
31f10 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
31f20 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
31f30 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
31f40 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31f50 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
31f60 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
31f70 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
31f80 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
31f90 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
31fa0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
31fb0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
31fc0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
31fd0 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
31fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31ff0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
32000 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
32010 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
32020 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
32030 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32040 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
32050 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
32060 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
32070 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
32080 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
32090 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
320a0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
320b0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
320c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
320d0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
320e0 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
320f0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
32100 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
32110 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
32120 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
32130 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
32140 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
32150 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
32160 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
32170 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
32180 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
32190 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
321a0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
321b0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
321c0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
321d0 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
321e0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
321f0 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
32200 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
32210 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
32220 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
32230 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32240 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
32250 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
32260 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
32270 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32280 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
32290 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
322a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
322b0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
322c0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
322d0 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
322e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
322f0 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
32300 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
32310 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
32320 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
32330 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
32340 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
32350 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
32360 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
32370 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
32380 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
32390 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
323a0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
323b0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
323c0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
323d0 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
323e0 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
323f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
32400 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
32410 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
32420 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
32430 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
32440 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
32450 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
32460 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
32470 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
32480 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
32490 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
324a0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
324b0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
324c0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
324d0 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
324e0 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
324f0 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
32500 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
32510 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
32520 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
32530 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
32540 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
32550 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
32560 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
32570 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
32580 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
32590 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
325a0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
325b0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
325c0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
325d0 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
325e0 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
325f0 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
32600 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
32610 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
32620 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
32630 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
32640 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32650 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32660 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
32670 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32680 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
32690 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
326a0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
326b0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
326c0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
326d0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
326e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
326f0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
32700 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32710 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
32720 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
32730 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
32740 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
32750 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
32760 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
32770 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
32780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32790 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
327a0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
327b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
327c0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
327d0 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
327e0 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
327f0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
32800 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
32810 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
32820 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
32830 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
32840 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32850 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
32860 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
32870 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
32880 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
32890 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
328a0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
328b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
328c0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
328d0 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
328e0 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
328f0 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
32900 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
32910 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
32920 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
32930 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
32940 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
32950 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
32960 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
32970 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
32980 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
32990 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
329a0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
329b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
329c0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
329d0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
329e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
329f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
32a00 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
32a10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32a20 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
32a30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32a40 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
32a50 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
32a60 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
32a70 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
32a80 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
32a90 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
32aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32ab0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32ac0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
32ad0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
32ae0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
32af0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
32b00 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
32b10 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
32b20 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
32b30 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
32b40 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
32b50 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
32b60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32b70 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
32b80 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
32b90 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
32ba0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
32bb0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
32bc0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
32bd0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
32be0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
32bf0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
32c00 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
32c10 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
32c20 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
32c30 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
32c40 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
32c50 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
32c60 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
32c70 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
32c80 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
32c90 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
32ca0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
32cb0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
32cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
32cd0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
32ce0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
32cf0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
32d00 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
32d10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
32d20 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
32d30 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
32d40 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
32d50 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
32d60 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
32d70 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
32d80 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
32d90 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32da0 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
32db0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
32dc0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
32dd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
32de0 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
32df0 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
32e00 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
32e10 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
32e20 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
32e30 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
32e40 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
32e50 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
32e60 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
32e70 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
32e80 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
32e90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
32ea0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
32eb0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
32ec0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
32ed0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
32ee0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
32ef0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
32f00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
32f10 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
32f20 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
32f30 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
32f40 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
32f50 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
32f60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
32f70 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
32f80 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
32f90 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
32fa0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
32fb0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
32fc0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
32fd0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
32fe0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
32ff0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
33000 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
33010 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
33020 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
33030 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
33040 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
33050 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
33060 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
33070 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
33080 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
33090 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
330a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
330b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
330c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
330d0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
330e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
330f0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
33100 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
33110 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
33120 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
33130 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
33140 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
33150 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
33160 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
33170 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33180 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
33190 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
331a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
331b0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
331c0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
331d0 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
331e0 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
331f0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
33200 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
33210 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
33220 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
33230 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
33240 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
33250 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
33260 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
33270 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
33280 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
33290 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
332a0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
332b0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
332c0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
332d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
332e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
332f0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
33300 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
33310 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
33320 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
33330 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
33340 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
33350 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
33360 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
33370 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
33380 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
33390 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
333a0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
333b0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
333c0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
333d0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
333e0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
333f0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
33400 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
33410 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
33420 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
33430 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
33440 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33450 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
33460 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
33470 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
33480 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
33490 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
334a0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
334b0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
334c0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
334d0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
334e0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
334f0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
33500 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
33510 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
33520 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
33530 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
33540 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
33550 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
33560 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
33570 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
33580 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
33590 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
335a0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
335b0 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
335c0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
335d0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
335e0 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
335f0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
33600 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
33610 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
33620 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
33630 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
33640 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
33650 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
33660 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
33670 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
33680 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
33690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
336a0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
336b0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
336c0 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
336d0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
336e0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
336f0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
33700 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
33710 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
33720 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
33730 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
33740 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
33750 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
33760 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
33770 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
33780 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
33790 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
337a0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
337b0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
337c0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
337d0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
337e0 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
337f0 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
33800 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
33810 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
33820 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
33830 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
33840 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
33850 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
33860 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
33870 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
33880 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
33890 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
338a0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
338b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
338c0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
338d0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
338e0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
338f0 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
33900 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
33910 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
33920 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
33930 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
33940 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
33950 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
33960 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
33970 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
33980 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
33990 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
339a0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
339b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
339c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
339d0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
339e0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
339f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
33a00 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
33a10 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
33a20 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
33a30 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
33a40 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
33a50 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
33a60 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
33a70 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
33a80 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
33a90 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
33aa0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
33ab0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
33ac0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
33ad0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
33ae0 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
33af0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
33b00 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
33b10 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
33b20 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
33b30 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
33b40 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
33b50 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
33b60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
33b70 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
33b80 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
33b90 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
33ba0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
33bb0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
33bc0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
33bd0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
33be0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
33bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33c00 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
33c10 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
33c20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
33c30 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
33c40 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
33c50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
33c60 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
33c70 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
33c80 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
33c90 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
33ca0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
33cb0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
33cc0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
33cd0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
33ce0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
33cf0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
33d00 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
33d10 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
33d20 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
33d30 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
33d40 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
33d50 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
33d60 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
33d70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
33d80 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
33d90 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
33da0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
33db0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
33dc0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
33dd0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
33de0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
33df0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
33e00 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
33e10 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
33e20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
33e30 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
33e40 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
33e50 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
33e60 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
33e70 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
33e80 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
33e90 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
33ea0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
33eb0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
33ec0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
33ed0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
33ee0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
33ef0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
33f00 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
33f10 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
33f20 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
33f30 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
33f40 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
33f50 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
33f60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
33f70 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
33f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
33f90 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
33fa0 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
33fb0 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
33fc0 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
33fd0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
33fe0 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
33ff0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
34000 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
34010 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
34020 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34030 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
34040 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
34050 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
34060 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
34070 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
34080 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
34090 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
340a0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
340b0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
340c0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
340d0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
340e0 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
340f0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
34100 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
34110 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
34120 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
34130 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
34140 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
34150 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
34160 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
34170 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
34180 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
34190 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
341a0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
341b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
341c0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
341d0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
341e0 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
341f0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
34200 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
34210 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
34220 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
34230 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
34240 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
34250 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
34260 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
34270 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
34280 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
34290 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
342a0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
342b0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
342c0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
342d0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
342e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
342f0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
34300 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
34310 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
34320 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
34330 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
34340 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
34350 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
34360 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
34370 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
34380 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
34390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
343a0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
343b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
343c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
343d0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
343e0 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
343f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
34400 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
34410 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34420 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
34430 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
34440 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
34450 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34460 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
34470 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
34480 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
34490 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
344a0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
344b0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
344c0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
344d0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
344e0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
344f0 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
34500 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
34510 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
34520 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
34530 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
34540 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72  The Filename For
34550 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
34560 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
34570 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c  e sqlite3_db_fil
34580 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72  ename(D,N) inter
34590 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
345a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65  ointer to a file
345b0 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  name.** associat
345c0 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ed with database
345d0 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e   N of connection
345e0 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64   D.  ^The main d
345f0 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
34600 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  has the name "ma
34610 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69  in".  If there i
34620 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61  s no attached da
34630 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20  tabase N on the 
34640 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
34650 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20  ection D, or if 
34660 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20  database N is a 
34670 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d  temporary or in-
34680 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c  memory database,
34690 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20   then.** a NULL 
346a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
346b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
346c0 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65  filename returne
346d0 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
346e0 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74  on is the output
346f0 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c   of the.** xFull
34700 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20  Pathname method 
34710 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e  of the [VFS].  ^
34720 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
34730 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
34740 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c  will be an absol
34750 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76  ute pathname, ev
34760 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61  en if the filena
34770 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70  me used.** to op
34780 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
34790 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61  originally was a
347a0 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65   URI or relative
347b0 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f   pathname..*/.co
347c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
347d0 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71  3_db_filename(sq
347e0 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
347f0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
34800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34810 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
34820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34830 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
34840 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34850 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
34860 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
34870 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
34880 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
34890 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
348a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
348b0 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
348c0 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
348d0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
348e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
348f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
34900 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
34910 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
34920 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
34930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34940 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
34950 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34960 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
34970 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
34980 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
34990 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
349a0 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
349b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
349c0 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
349d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
349e0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
349f0 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
34a00 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
34a10 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
34a20 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
34a30 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
34a40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
34a50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
34a60 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
34a70 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
34a80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34a90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34aa0 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
34ab0 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
34ac0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
34ad0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34ae0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
34af0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
34b00 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
34b10 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
34b20 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
34b30 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
34b40 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
34b50 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
34b60 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
34b70 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
34b80 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
34b90 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
34ba0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
34bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
34bc0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
34bd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
34be0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
34bf0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
34c00 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
34c10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
34c20 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
34c30 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
34c40 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
34c50 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
34c60 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
34c70 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
34c80 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
34c90 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
34ca0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
34cb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34cc0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
34cd0 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
34ce0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
34cf0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
34d00 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
34d10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
34d20 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
34d30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
34d40 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
34d50 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
34d60 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
34d70 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
34d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
34d90 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
34da0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
34db0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
34dc0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
34dd0 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
34de0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
34df0 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
34e00 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
34e10 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
34e20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34e30 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
34e40 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
34e50 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
34e60 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
34e70 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20  *.** The commit 
34e80 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  and rollback hoo
34e90 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20  k callbacks are 
34ea0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a  not reentrant..*
34eb0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
34ec0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
34ed0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
34ee0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
34ef0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
34f00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
34f10 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
34f20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
34f30 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
34f40 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
34f50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
34f60 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
34f70 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
34f80 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
34f90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
34fa0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
34fb0 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
34fc0 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
34fd0 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
34fe0 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
34ff0 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61  e that running a
35000 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61  ny other SQL sta
35010 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69  tements, includi
35020 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ng SELECT statem
35030 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65  ents,.** or mere
35040 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ly calling [sqli
35050 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35060 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
35070 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69  tep()] will modi
35080 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
35090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
350a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
350b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
350c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
350d0 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
350e0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
350f0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
35100 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
35110 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
35120 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
35130 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
35140 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
35150 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
35160 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
35170 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
35180 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
35190 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
351a0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
351b0 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
351c0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
351d0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
351e0 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
351f0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
35200 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
35210 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
35220 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
35230 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
35240 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
35250 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
35260 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
35270 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
35280 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
35290 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
352a0 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
352b0 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
352c0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
352d0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
352e0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
352f0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
35300 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
35310 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
35320 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
35330 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
35340 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
35350 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
35360 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
35370 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
35380 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
35390 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
353a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
353b0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
353c0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
353d0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
353e0 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
353f0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
35400 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35410 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
35420 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
35430 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
35440 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
35450 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
35460 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
35470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35480 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
35490 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
354a0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
354b0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
354c0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
354d0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
354e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
354f0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
35500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
35510 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
35520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
35530 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
35540 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
35550 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
35560 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
35570 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
35580 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
35590 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
355a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
355b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
355c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
355d0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
355e0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
355f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
35600 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
35610 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
35620 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
35630 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
35640 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
35650 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
35660 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
35670 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
35680 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
35690 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
356a0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
356b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
356c0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
356d0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
356e0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
356f0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
35700 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
35710 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
35720 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
35730 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
35740 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
35750 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
35760 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
35770 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
35780 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
35790 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
357a0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
357b0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
357c0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
357d0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
357e0 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
357f0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
35800 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
35810 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
35820 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
35830 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
35840 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
35850 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
35860 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
35870 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
35880 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
35890 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
358a0 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
358b0 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
358c0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
358d0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
358e0 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
358f0 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
35900 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
35910 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
35920 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
35930 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
35940 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
35950 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
35960 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
35970 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
35980 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
35990 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
359a0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
359b0 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
359c0 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
359d0 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
359e0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
359f0 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
35a00 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
35a10 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
35a20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
35a30 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
35a40 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
35a50 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
35a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
35a70 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
35a80 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
35a90 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
35aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
35ab0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
35ac0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
35ad0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
35ae0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
35af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
35b00 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
35b10 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
35b20 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
35b30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
35b40 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
35b50 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
35b60 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
35b70 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
35b80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
35b90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
35ba0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
35bb0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
35bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
35bd0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
35be0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
35bf0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
35c00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35c10 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
35c20 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
35c30 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
35c40 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
35c50 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
35c60 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
35c70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35c80 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
35c90 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
35ca0 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
35cb0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
35cc0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
35cd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35ce0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
35cf0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
35d00 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35d10 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
35d20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
35d30 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
35d40 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
35d50 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
35d60 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
35d70 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
35d80 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
35d90 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
35da0 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
35db0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
35dc0 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
35dd0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
35de0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
35df0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
35e00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
35e10 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
35e20 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
35e30 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
35e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
35e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
35e60 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
35e70 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
35e80 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
35e90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
35ea0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
35eb0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
35ec0 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
35ed0 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
35ee0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
35ef0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
35f00 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
35f10 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
35f20 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
35f30 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
35f40 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
35f50 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
35f60 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
35f70 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
35f80 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
35f90 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
35fa0 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
35fb0 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
35fc0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
35fd0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
35fe0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
35ff0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
36000 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
36010 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
36020 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
36030 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
36040 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36050 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
36060 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
36070 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
36080 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
36090 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
360a0 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
360b0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
360c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
360d0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
360e0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
360f0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
36100 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
36110 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
36120 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
36130 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
36140 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
36150 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
36160 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
36170 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
36180 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
36190 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
361a0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
361b0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
361c0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
361d0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
361e0 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
361f0 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
36200 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
36210 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
36220 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
36230 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
36240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
36250 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
36260 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
36270 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36280 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
36290 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
362a0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
362b0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
362c0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
362d0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
362e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
362f0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
36300 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
36310 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
36320 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
36330 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
36340 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
36350 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
36360 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
36370 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
36380 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
36390 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
363a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
363b0 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
363c0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
363d0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
363e0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
363f0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
36400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36410 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36420 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
36430 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
36440 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
36450 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
36460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
36470 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
36480 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  EMENT]..**.** Se
36490 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
364a0 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  _db_release_memo
364b0 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ry()].*/.int sql
364c0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
364d0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
364e0 20 43 41 50 49 33 52 45 46 3a 20 46 72 65 65 20   CAPI3REF: Free 
364f0 4d 65 6d 6f 72 79 20 55 73 65 64 20 42 79 20 41  Memory Used By A
36500 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
36510 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
36520 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61  sqlite3_db_relea
36530 73 65 5f 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74  se_memory(D) int
36540 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
36550 74 6f 20 66 72 65 65 20 61 73 20 6d 75 63 68 20  to free as much 
36560 68 65 61 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  heap.** memory a
36570 73 20 70 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20  s possible from 
36580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36590 69 6f 6e 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68  ion D. Unlike th
365a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  e.** [sqlite3_re
365b0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
365c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 69 73 20  interface, this 
365d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 66 66  interface is eff
365e0 65 63 74 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e  ect even.** when
365f0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e   then [SQLITE_EN
36600 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
36610 47 45 4d 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d  GEMENT] compile-
36620 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  time option is.*
36630 2a 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  * omitted..**.**
36640 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36650 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36660 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ry()].*/.int sql
36670 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f  ite3_db_release_
36680 6d 65 6d 6f 72 79 28 73 71 6c 69 74 65 33 2a 29  memory(sqlite3*)
36690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
366a0 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
366b0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
366c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
366d0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
366e0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
366f0 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72  sets and/or quer
36700 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  ies the.** soft 
36710 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
36720 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
36730 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
36740 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
36750 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73  te..** ^SQLite s
36760 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68  trives to keep h
36770 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69  eap memory utili
36780 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65  zation below the
36790 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69   soft heap.** li
367a0 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20  mit by reducing 
367b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
367c0 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20  ges held in the 
367d0 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73  page cache.** as
367e0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61   heap memory usa
367f0 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74  ges approaches t
36800 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  he limit..** ^Th
36810 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36820 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61  t is "soft" beca
36830 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20  use even though 
36840 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
36850 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20  o stay.** below 
36860 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69  the limit, it wi
36870 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69  ll exceed the li
36880 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20  mit rather than 
36890 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b  generate.** an [
368a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72  SQLITE_NOMEM] er
368b0 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ror.  In other w
368c0 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68  ords, the soft h
368d0 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73  eap limit .** is
368e0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
368f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
36900 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
36910 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
36920 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20  imit64() is the 
36930 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73  size of.** the s
36940 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70  oft heap limit p
36950 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
36960 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69 6e  , or negative in
36970 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 0a   the case of an.
36980 2a 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  ** error.  ^If t
36990 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
369a0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65   negative.** the
369b0 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d  n no change is m
369c0 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20  ade to the soft 
369d0 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e  heap limit.  Hen
369e0 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ce, the current.
369f0 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  ** size of the s
36a00 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
36a10 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
36a20 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   by invoking.** 
36a30 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
36a40 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68  p_limit64() with
36a50 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75   a negative argu
36a60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ment..**.** ^If 
36a70 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
36a80 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  s zero then the 
36a90 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
36aa0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
36ab0 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65  ** ^(The soft he
36ac0 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  ap limit is not 
36ad0 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20  enforced in the 
36ae0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
36af0 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65  tation.** if one
36b00 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c   or more of foll
36b10 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73  owing conditions
36b20 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a   are true:.**.**
36b30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
36b40 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36b50 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f  t is set to zero
36b60 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79  ..** <li> Memory
36b70 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64   accounting is d
36b80 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
36b90 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74  combination of t
36ba0 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  he.**      [sqli
36bb0 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
36bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
36bd0 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74  ATUS],...) start
36be0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64  -time option and
36bf0 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51  .**      the [SQ
36c00 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
36c10 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d  STATUS] compile-
36c20 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
36c30 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74  <li> An alternat
36c40 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69  ive page cache i
36c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
36c60 20 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67   specified using
36c70 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
36c80 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
36c90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
36ca0 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20  ],...)..** <li> 
36cb0 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61  The page cache a
36cc0 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74  llocates from it
36cd0 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f  s own memory poo
36ce0 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20  l supplied.**   
36cf0 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
36d00 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
36d10 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
36d20 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61  ,...) rather tha
36d30 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74  n.**      from t
36d40 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c  he heap..** </ul
36d50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e  >)^.**.** Beginn
36d60 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
36d70 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74  version 3.7.3, t
36d80 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
36d90 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a  it is enforced.*
36da0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
36db0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
36dc0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
36dd0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
36de0 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  ENT].** compile-
36df0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69  time option is i
36e00 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53  nvoked.  With [S
36e10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
36e20 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
36e30 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61  .** the soft hea
36e40 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72  p limit is enfor
36e50 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d  ced on every mem
36e60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  ory allocation. 
36e70 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c   Without.** [SQL
36e80 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
36e90 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74  Y_MANAGEMENT], t
36ea0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
36eb0 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72  it is only enfor
36ec0 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f  ced.** when memo
36ed0 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
36ee0 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68  by the page cach
36ef0 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67  e.  Testing sugg
36f00 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73  ests that becaus
36f10 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61  e.** the page ca
36f20 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f  che is the predo
36f30 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73  minate memory us
36f40 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f  er in SQLite, mo
36f50 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
36f60 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20  ns will achieve 
36f70 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65  adequate soft he
36f80 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65  ap limit enforce
36f90 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ment without.** 
36fa0 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49  the use of [SQLI
36fb0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
36fc0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a  _MANAGEMENT]..**
36fd0 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74  .** The circumst
36fe0 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63  ances under whic
36ff0 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e  h SQLite will en
37000 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68  force the soft h
37010 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a  eap limit may.**
37020 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75   changes in futu
37030 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
37040 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  QLite..*/.sqlite
37050 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
37060 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
37070 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  4(sqlite3_int64 
37080 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
37090 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
370a0 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20  Soft Heap Limit 
370b0 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50  Interface.** DEP
370c0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
370d0 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74  is is a deprecat
370e0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
370f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
37100 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
37110 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  ** interface.  T
37120 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70  his routine is p
37130 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74  rovided for hist
37140 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
37150 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41  lity.** only.  A
37160 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  ll new applicati
37170 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ons should use t
37180 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
37190 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
371a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61  ()] interface ra
371b0 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f  ther than this o
371c0 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  ne..*/.SQLITE_DE
371d0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
371e0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
371f0 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a  limit(int N);...
37200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37210 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
37220 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
37230 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  Of A Table.**.**
37240 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
37250 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20  eturns metadata 
37260 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
37270 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
37280 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73  cific.** databas
37290 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  e table accessib
372a0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61  le using the [da
372b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
372c0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73  n] handle.** pas
372d0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
372e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
372f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  nt..**.** ^The c
37300 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
37310 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
37320 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
37330 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
37340 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  o.** this functi
37350 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  on. ^The second 
37360 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
37370 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
37380 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37390 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
373a0 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61  emp", or an atta
373b0 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
373c0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
373d0 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
373e0 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74   or NULL. ^If it
373f0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
37400 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
37410 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
37420 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
37430 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
37440 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
37450 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
37460 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
37470 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
37480 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
37490 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ces..**.** ^The 
374a0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
374b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
374c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
374d0 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
374e0 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66  olumn.** name of
374f0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
37500 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
37510 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
37520 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ese parameters.*
37530 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
37540 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69  *.** ^Metadata i
37550 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
37560 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
37570 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
37580 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a  ssed as the 5th.
37590 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  ** and subsequen
375a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
375b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
375c0 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67  Any of these arg
375d0 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a  uments may be.**
375e0 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
375f0 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
37600 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
37610 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d  f metadata is om
37620 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  itted..**.** ^(<
37630 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
37640 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
37650 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61  >.** <tr><th> Pa
37660 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74  rameter <th> Out
37670 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  put<br>Type <th>
37680 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
37690 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68  .** <tr><td> 5th
376a0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
376b0 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65  * <td> Data type
376c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68  .** <tr><td> 6th
376d0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
376e0 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64  * <td> Name of d
376f0 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
37700 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72   sequence.** <tr
37710 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69  ><td> 7th <td> i
37720 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
37730 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68  True if column h
37740 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
37750 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e  nstraint.** <tr>
37760 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e  <td> 8th <td> in
37770 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
37780 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
37790 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
377a0 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e  MARY KEY.** <tr>
377b0 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e  <td> 9th <td> in
377c0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
377d0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
377e0 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d   [AUTOINCREMENT]
377f0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
37800 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
37810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
37820 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
37830 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
37840 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
37850 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61  for the.** decla
37860 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
37870 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37880 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
37890 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
378a0 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53  ** call to any S
378b0 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  QLite API functi
378c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
378d0 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
378e0 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
378f0 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20  view, an [error 
37900 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
37910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
37920 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
37930 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f  n is "rowid", "o
37940 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22  id" or "_rowid_"
37950 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45   and an.** [INTE
37960 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
37970 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e   column has been
37980 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
37990 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  ared, then the o
379a0 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74  utput.** paramet
379b0 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20  ers are set for 
379c0 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64  the explicitly d
379d0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20  eclared column. 
379e0 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f  ^(If there is no
379f0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64  .** explicitly d
37a00 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52  eclared [INTEGER
37a10 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
37a20 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f  lumn, then the o
37a30 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74  utput.** paramet
37a40 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66  ers are set as f
37a50 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
37a60 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
37a70 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
37a80 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
37a90 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
37aa0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
37ab0 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
37ac0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
37ad0 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
37ae0 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29  nt: 0.** </pre>)
37af0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66  ^.**.** ^(This f
37b00 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
37b10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
37b20 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
37b30 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
37b40 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
37b50 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
37b60 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
37b70 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
37b80 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
37b90 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
37ba0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
37bb0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
37bc0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65  error message le
37bd0 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61  ft.** in the [da
37be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37bf0 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  n] (to be retrie
37c00 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
37c10 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a  3_errmsg()).)^.*
37c20 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69  *.** ^This API i
37c30 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
37c40 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
37c50 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
37c60 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
37c70 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
37c80 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
37c90 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
37ca0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
37cb0 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
37cc0 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
37cd0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37ce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
37cf0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
37d00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37d10 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37d20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
37d30 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
37d40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
37d50 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
37d60 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
37d70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
37d80 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
37d90 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
37da0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
37db0 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
37dc0 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
37dd0 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
37de0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
37df0 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
37e00 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
37e10 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
37e20 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
37e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37e40 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
37e50 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
37e60 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
37e70 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
37e80 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
37e90 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
37ea0 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
37eb0 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
37ec0 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
37ed0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
37ee0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
37ef0 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
37f00 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
37f10 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
37f20 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  tension.**.** ^T
37f30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f  his interface lo
37f40 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78  ads an SQLite ex
37f50 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
37f60 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66  from the named f
37f70 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ile..**.** ^The 
37f80 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
37f90 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
37fa0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ce attempts to l
37fb0 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65  oad an.** SQLite
37fc0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
37fd0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
37fe0 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a  the file zFile..
37ff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79  **.** ^The entry
38000 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
38010 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62  .** ^zProc may b
38020 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61  e 0, in which ca
38030 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
38040 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  he entry point.*
38050 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73  * defaults to "s
38060 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
38070 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20  _init"..** ^The 
38080 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
38090 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
380a0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ce returns.** [S
380b0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
380c0 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45  cess and [SQLITE
380d0 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74  _ERROR] if somet
380e0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
380f0 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
38100 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72   occurs and pzEr
38110 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74  rMsg is not 0, t
38120 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  hen the.** [sqli
38130 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
38140 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  on()] interface 
38150 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
38160 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d  .** fill *pzErrM
38170 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
38180 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
38190 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f  d in memory.** o
381a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
381b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
381c0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
381d0 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ction.** should 
381e0 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79  free this memory
381f0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
38200 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
38210 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
38220 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
38230 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nabled using.** 
38240 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
38250 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
38260 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ] prior to calli
38270 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20  ng this API,.** 
38280 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
38290 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
382a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ned..**.** See a
382b0 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78  lso the [load_ex
382c0 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75  tension() SQL fu
382d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20  nction]..*/.int 
382e0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
382f0 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
38300 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
38310 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
38320 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
38330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38340 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
38350 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
38360 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
38370 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
38380 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
38390 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
383a0 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
383b0 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
383c0 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
383d0 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
383e0 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
383f0 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
38400 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
38410 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
38420 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
38430 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
38440 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
38450 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20  *.** ^So as not 
38460 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
38470 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
38480 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
38490 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
384a0 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
384b0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
384c0 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
384d0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
384e0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
384f0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
38500 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
38510 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
38520 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
38530 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
38540 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
38550 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
38560 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
38570 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74   off..**.** ^Ext
38580 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
38590 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
385a0 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  . See ticket #18
385b0 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65  63..** ^Call the
385c0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
385d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
385e0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e   routine with on
385f0 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72  off==1.** to tur
38600 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  n extension load
38610 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20  ing on and call 
38620 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
38630 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62   to turn.** it b
38640 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
38650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
38660 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
38670 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
38680 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
38690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
386a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
386b0 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b   Statically Link
386c0 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a  ed Extensions.**
386d0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
386e0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ace causes the x
386f0 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e  EntryPoint() fun
38700 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
38710 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ked for.** each 
38720 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
38730 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69  nnection] that i
38740 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
38750 69 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61  idea here is tha
38760 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  t.** xEntryPoint
38770 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20  () is the entry 
38780 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74  point for a stat
38790 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51  ically linked SQ
387a0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a  Lite extension.*
387b0 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20  * that is to be 
387c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f  automatically lo
387d0 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65  aded into all ne
387e0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
387f0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ctions..**.** ^(
38800 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20  Even though the 
38810 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79  function prototy
38820 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45  pe shows that xE
38830 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65  ntryPoint() take
38840 73 0a 2a 2a 20 6e 6