/ Hex Artifact Content
Login

Artifact bcddafefaea18c0af74df5f2b1c4067c4c7013e6:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5b90: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5ba0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5bb0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5bc0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5bd0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5be0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5bf0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5c00: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5c10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5c20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5c30: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5c40: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5c50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5c60: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5c70: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c90: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5ca0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5cb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ce0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5d00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5d50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5d90: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5da0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dc0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5dd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5de0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5e20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5e50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5e60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5e70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5ea0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5eb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ec0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ee0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5ef0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5f00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5f40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5f70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5f80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5fb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5fc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5ff0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
6000: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6020: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6030: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6070: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
60b0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
60c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
60d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
6100: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6110: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6120: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6140: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6150: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6160: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6190: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
61a0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
61b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
61c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
61f0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6220: 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 54  OPEN_FILEPROTECT
6230: 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20 20  ION_MASK        
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6250: 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30 30           0x00700
6260: 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64  000../* Reserved
6270: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6280: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6290: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
62a0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
62b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
62c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
62d0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
62e0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6310: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6320: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6330: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6340: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6350: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6360: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6370: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6380: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6390: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
63a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
63b0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
63c0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
63e0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
63f0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6400: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6410: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6420: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6430: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6440: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6450: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6460: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6470: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6480: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6490: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
64a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
64b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
64c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
64d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
64f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6500: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6510: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6520: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6530: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6540: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6550: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6560: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6570: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6580: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6590: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
65a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
65b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
65c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
65d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
65e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
65f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6600: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6610: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6620: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6630: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6640: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6650: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6660: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6670: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6680: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6690: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
66a0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
66b0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
66c0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
66d0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
66e0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
66f0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6700: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6710: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6720: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6730: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6740: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6750: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6760: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  te that a file c
6770: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6780: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6790: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
67a0: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
67b0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
67c0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
67d0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
67e0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
67f0: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6800: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6810: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6820: 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  eges..*/.#define
6830: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6840: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6850: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6870: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6880: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6890: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
68a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68b0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
68c0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
68d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68e0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
68f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6900: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6910: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6920: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6930: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6990: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
69a0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6a30: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6a40: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6aa0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6ab0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6ae0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6af0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6b10: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  LE              
6b20: 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a  0x00002000../*.*
6b30: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6b40: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6b50: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6b60: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6b70: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6b80: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6b90: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6ba0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6bb0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6bc0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6bd0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6be0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6bf0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6c00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6c10: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c30: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6c50: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6c60: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6c70: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6c80: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6c90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6ca0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6cb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6cc0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6cd0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6ce0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6cf0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6d00: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6d10: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6d20: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6d30: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6d40: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6d50: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6d60: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6d70: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6d80: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6d90: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6da0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6db0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6dc0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6dd0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6de0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6df0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6e00: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6e10: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6e20: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6e30: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6e40: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6e50: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6e60: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6e70: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6e80: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6e90: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6ea0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6eb0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6ec0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6ed0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6ee0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6ef0: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6f00: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6f10: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6f20: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6f30: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6f40: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6f50: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6f60: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
6f70: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6f80: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
6f90: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
6fa0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
6fb0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6fc0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6fd0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6fe0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6ff0: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7000: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7010: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7020: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7030: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7040: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7050: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7060: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
7070: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
7080: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
7090: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
70a0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
70b0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
70c0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
70d0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
70e0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
70f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7100: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7110: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7120: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7130: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7140: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7150: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7160: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7170: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7180: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
7190: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
71a0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
71b0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
71c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
71d0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
71e0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
71f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7200: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7210: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7220: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7230: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7250: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7260: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7270: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7280: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
7290: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
72a0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
72b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
72c0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
72d0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
72e0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
72f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7300: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7310: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7320: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7330: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7340: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7350: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7360: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7370: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7380: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7390: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
73a0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
73b0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
73c0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
73d0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
73e0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
73f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7400: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7410: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7420: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7430: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7440: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7450: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7460: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7470: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7480: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7490: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
74a0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
74b0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
74c0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
74d0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
74e0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
74f0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7500: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7510: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7520: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7530: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7540: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7550: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7560: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7570: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7580: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7590: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
75a0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
75b0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
75c0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
75d0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
75e0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
75f0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7600: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7610: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7620: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7630: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7640: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7650: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7660: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7670: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7680: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7690: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
76a0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
76b0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
76c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
76d0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
76e0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
76f0: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7700: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7710: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7720: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7730: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7740: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7750: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7760: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7770: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7780: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7790: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
77a0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
77b0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
77c0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
77d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
77e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
77f0: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7800: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7810: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7820: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7830: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7840: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7850: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7860: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7870: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7880: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7890: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
78a0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
78b0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
78c0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
78d0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
78e0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
78f0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7900: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7910: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7920: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7930: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7940: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7950: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7960: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7970: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7980: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7990: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
79a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
79b0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
79c0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
79d0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
79e0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
79f0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7a00: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7a10: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7a20: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7a30: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7a50: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7a60: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7a70: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7a80: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7a90: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7aa0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7ab0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7ac0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7ad0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7ae0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7af0: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7b00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7b10: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7b20: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7b30: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7b40: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7b50: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7b60: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7b70: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7b80: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7b90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7ba0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7bb0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7bc0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7bd0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7be0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7bf0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7c00: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7c10: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7c20: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7c30: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7c40: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7c50: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7c60: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7c70: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7c80: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7c90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7ca0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7cb0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7cc0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7cd0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7ce0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7cf0: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7d00: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7d10: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7d20: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7d30: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7d40: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7d50: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7d60: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7d70: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7d80: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7d90: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7da0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7db0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
7dc0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
7dd0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7de0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7df0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7e00: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7e10: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7e20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7e30: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7e40: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7e50: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7e60: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7e70: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7e80: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7e90: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7ea0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7eb0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7ec0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7ed0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7ee0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7ef0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7f00: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7f10: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7f20: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7f30: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7f40: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7f50: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7f60: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7f70: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7f80: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7f90: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7fa0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7fb0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7fc0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7fd0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7fe0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7ff0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8000: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8010: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8020: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8030: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8040: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8050: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8060: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
8070: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8080: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
8090: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80a0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
80b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80c0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
80d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80e0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
80f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8100: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8120: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8130: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8140: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8160: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8170: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8180: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
8190: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
81a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
81b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
81c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
81d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
81e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
81f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8200: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8210: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8220: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8230: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8240: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8250: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8260: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8270: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8280: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
8290: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
82a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
82b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
82c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
82d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
82e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
82f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8300: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8310: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8320: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8330: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8340: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8350: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8360: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8370: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8380: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
8390: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
83a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
83b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
83c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
83d0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
83e0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
83f0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8400: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8410: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8420: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8430: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8440: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8450: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8460: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8470: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8480: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
8490: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
84a0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
84b0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
84c0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
84d0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
84e0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
84f0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8500: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8510: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8520: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8530: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8540: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8550: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8560: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8570: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8580: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
85c0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
85d0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
85e0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
85f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8600: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8610: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8620: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8630: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8640: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8650: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8660: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8670: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8680: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8690: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
86a0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
86b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
86c0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
86d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
86e0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
86f0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8700: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8710: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8720: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8730: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8740: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8750: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8760: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8770: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8780: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8790: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
87a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
87b0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
87c0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
87d0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
87e0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
87f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8800: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8810: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8820: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8830: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8840: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8850: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8860: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8870: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8880: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8890: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
88a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
88b0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
88c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
88d0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
88e0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
88f0: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8930: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8940: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8950: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8960: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8970: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8980: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8990: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
89a0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
89b0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
89c0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
89d0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
89e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
89f0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8a00: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8a10: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
8a20: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8a30: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
8a40: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
8a50: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8a60: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8a70: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8a80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8a90: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8aa0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8ab0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8ac0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8ad0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8ae0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8af0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8b00: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8b10: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8b20: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8b30: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8b40: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8b50: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8b60: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8b70: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8b80: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8b90: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8ba0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8bb0: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8bc0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8bd0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8be0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8bf0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8c00: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8c10: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8c20: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8c30: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8c40: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8c50: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8c60: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
8c70: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
8c80: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
8c90: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
8ca0: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
8cb0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8cc0: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
8cd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8ce0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
8cf0: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
8d00: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
8d10: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
8d20: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
8d30: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
8d40: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
8d50: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
8d60: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
8d70: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
8d80: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
8d90: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
8da0: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
8db0: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
8dc0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
8dd0: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
8de0: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
8df0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
8e00: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
8e10: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
8e20: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
8e30: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
8e40: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
8e50: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
8e60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8e70: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
8e80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
8e90: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
8ea0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
8eb0: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
8ec0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
8ed0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
8ee0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
8ef0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
8f00: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
8f10: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
8f20: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
8f30: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
8f40: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
8f50: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
8f60: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
8f70: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
8f80: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
8f90: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
8fa0: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
8fb0: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
8fc0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
8fd0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
8fe0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
8ff0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9000: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9010: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9020: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9030: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9040: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9050: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9060: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9070: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9080: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9090: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
90a0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
90b0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
90c0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
90d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
90e0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
90f0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9100: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9110: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
9120: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9130: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
9140: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
9150: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
9160: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
9170: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9180: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
9190: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
91a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
91b0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
91c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
91d0: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
91e0: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
91f0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9200: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9210: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9220: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9230: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9240: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
9250: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
9260: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
9270: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
9280: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
9290: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
92a0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
92b0: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
92c0: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
92d0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
92e0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
92f0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9300: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9310: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9320: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9330: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9340: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
9350: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
9360: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
9370: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
9380: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9390: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
93a0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
93b0: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
93c0: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
93d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
93e0: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
93f0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9400: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9410: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9420: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9430: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9440: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9450: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
9460: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9470: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9480: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
9490: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
94a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
94b0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
94c0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
94d0: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
94e0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
94f0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9500: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9510: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9520: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9530: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9540: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
9550: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9560: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
9570: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9580: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9590: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
95a0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
95b0: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
95c0: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
95d0: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
95e0: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
95f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9600: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9610: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9620: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9630: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9640: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9650: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9660: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9670: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9680: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9690: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
96a0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
96b0: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
96c0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
96d0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
96e0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
96f0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9700: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9710: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9720: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9730: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9740: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9750: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9760: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9770: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9780: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9790: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
97a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
97b0: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
97c0: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
97d0: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
97e0: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
97f0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9800: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9810: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9820: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9830: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9840: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9850: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9860: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9870: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9880: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9890: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
98a0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
98b0: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
98c0: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
98d0: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
98e0: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
98f0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9900: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9910: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9920: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9930: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9940: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9950: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9960: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9970: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9980: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9990: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
99a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
99b0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
99c0: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
99d0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
99e0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
99f0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9a00: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9a10: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9a20: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9a30: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9a40: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9a50: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9a60: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9a70: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9a80: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9a90: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9aa0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9ab0: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9ac0: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9ad0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9ae0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9af0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9b00: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9b10: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9b20: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9b30: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9b40: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9b50: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9b60: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b90: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9ba0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9bb0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9bc0: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
9bd0: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
9be0: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
9bf0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
9c00: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
9c10: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
9c20: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
9c30: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
9c40: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
9c50: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
9c60: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
9c70: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
9c80: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
9c90: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
9ca0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
9cb0: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
9cc0: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
9cd0: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
9ce0: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
9cf0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
9d00: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
9d10: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
9d20: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
9d30: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
9d40: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
9d50: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
9d60: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9d70: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
9d80: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9d90: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
9da0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9db0: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
9dc0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
9dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
9de0: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
9df0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
9e00: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
9e10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9e20: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
9e30: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
9e40: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
9e50: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
9e60: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
9e70: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
9e80: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
9e90: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
9eb0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
9ec0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
9ed0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
9ee0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
9ef0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
9f00: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
9f10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9f20: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f30: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
9f40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9f50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9f60: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9f70: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
9f80: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
9f90: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
9fa0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
9fb0: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
9fc0: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
9fd0: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
9fe0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
9ff0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a000: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a010: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a020: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a030: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a040: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a050: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a060: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a070: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a080: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a090: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a0a0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a0b0: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a0c0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a0d0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a0e0: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a0f0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a100: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a110: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a120: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a130: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a140: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a150: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a160: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a170: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a180: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a190: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a1a0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a1b0: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a1c0: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a1d0: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a1e0: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a1f0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a200: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a210: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a220: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a230: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a240: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a250: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a260: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a270: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a280: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a290: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a2a0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a2b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a2c0: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a2d0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a2e0: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a2f0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a300: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a310: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a320: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a330: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a340: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a350: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a360: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a370: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a380: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a390: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a3a0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a3b0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a3c0: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a3d0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a3e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a3f0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a400: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a410: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a420: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a430: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a440: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a450: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a460: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a470: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a480: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a490: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a4a0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a4b0: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a4c0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a4d0: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a4e0: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a4f0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a500: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a510: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a520: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a530: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a540: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a550: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a560: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a570: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
a580: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
a590: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
a5a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
a5b0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
a5c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
a5d0: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
a5e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
a5f0: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
a600: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
a610: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
a620: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
a630: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
a640: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
a650: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
a660: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a670: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
a680: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
a690: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
a6a0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
a6b0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
a6c0: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
a6d0: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
a6e0: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
a6f0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
a700: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
a710: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
a720: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
a730: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
a740: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
a750: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
a760: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
a770: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a780: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
a790: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
a7a0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
a7b0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
a7c0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
a7d0: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
a7e0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
a7f0: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
a800: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
a810: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
a820: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
a830: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
a840: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
a850: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
a860: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
a870: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
a880: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a890: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a8a0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
a8b0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
a8c0: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
a8d0: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
a8e0: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
a8f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a900: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
a910: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a920: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
a930: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
a940: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
a950: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
a960: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
a970: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
a980: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
a990: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
a9a0: 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ed statement.  ^
a9b0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
a9c0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a9d0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a9e0: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
a9f0: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
aa00: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
aa10: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
aa20: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
aa30: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
aa40: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
aa50: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
aa60: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
aa70: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
aa80: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
aa90: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
aaa0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
aab0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aac0: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
aad0: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
aae0: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
aaf0: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ab00: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ab10: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ab20: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
ab30: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
ab40: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
ab50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ab60: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
ab70: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ab80: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab90: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
aba0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
abb0: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
abc0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
abd0: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
abe0: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
abf0: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
ac00: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
ac10: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
ac20: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
ac30: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
ac40: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
ac50: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
ac60: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
ac70: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
ac80: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
ac90: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
aca0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
acb0: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
acc0: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
acd0: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
ace0: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
acf0: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
ad00: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
ad10: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
ad20: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
ad30: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
ad40: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
ad50: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
ad60: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
ad70: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
ad80: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
ad90: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
ada0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
adb0: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
adc0: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
add0: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
ade0: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
adf0: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
ae00: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
ae10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
ae20: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
ae30: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
ae40: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
ae50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
ae60: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
ae70: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
ae80: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
ae90: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
aeb0: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
aec0: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
aed0: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
aee0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
aef0: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
af00: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
af10: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
af20: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
af30: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
af40: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
af50: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
af60: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
af70: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
af80: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
af90: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
afa0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
afb0: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
afc0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
afd0: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
afe0: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
aff0: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b000: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b010: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b020: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b030: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b040: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b050: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b060: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b070: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b080: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b090: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b0a0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b0b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b0c0: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b0d0: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b0e0: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b0f0: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b100: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b110: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b120: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b130: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b140: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b150: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b160: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b170: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b180: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b190: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b1a0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b1b0: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b1c0: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b1d0: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b1e0: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b1f0: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b200: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b210: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b220: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b230: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b240: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b250: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b260: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b270: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b280: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b290: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b2a0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b2b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b2c0: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b2d0: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b2e0: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b2f0: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b300: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b310: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b320: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b330: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b340: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b350: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b360: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b370: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b380: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b390: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b3a0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b3b0: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b3c0: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b3d0: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b3e0: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b3f0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b400: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b410: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b420: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b430: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b440: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b450: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b460: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b470: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b480: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b490: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b4a0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b4b0: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b4c0: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b4d0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b4e0: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b4f0: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b500: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b510: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b520: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b530: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b540: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b550: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b560: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b570: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b580: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b590: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b5a0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b5b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b5c0: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b5d0: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b5e0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b5f0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b600: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b610: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b620: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b630: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b640: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b650: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b660: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b670: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f  efined..**.** </
b680: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
b690: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
b6a0: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
b6b0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
b6c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
b6d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b6e0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
b6f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
b700: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b710: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
b720: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
b730: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
b740: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
b750: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
b760: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
b770: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
b780: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
b790: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
b7a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b7b0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
b7c0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
b7d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7e0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
b7f0: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
b800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b810: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
b820: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
b830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b840: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
b850: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
b860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b870: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
b880: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
b890: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b8a0: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
b8b0: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
b8c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b8d0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
b8e0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
b8f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b900: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
b910: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
b920: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
b930: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
b940: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
b950: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b960: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
b970: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
b980: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b990: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b9a0: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
b9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b9c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b9d0: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
b9e0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b9f0: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
ba00: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
ba10: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
ba20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ba30: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
ba40: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
ba50: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
ba60: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
ba70: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
ba80: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
ba90: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
baa0: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bab0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bac0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bad0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bae0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
baf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
bb00: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bb10: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
bb20: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
bb30: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
bb40: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
bb50: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
bb60: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
bb70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bb80: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
bb90: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
bba0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
bbb0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
bbc0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
bbd0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
bbe0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
bbf0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
bc00: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
bc10: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
bc20: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
bc30: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
bc40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
bc50: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
bc60: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
bc70: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
bc80: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
bc90: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
bca0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
bcb0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
bcc0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
bcd0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
bce0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
bcf0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
bd00: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
bd10: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
bd20: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
bd30: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bd40: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bd50: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
bd60: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
bd70: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
bd80: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
bd90: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
bda0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
bdb0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
bdc0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
bdd0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
bde0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
bdf0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
be00: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
be10: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
be20: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
be30: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
be40: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
be50: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
be60: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
be70: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
be80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
be90: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
bea0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
beb0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
bec0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
bed0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
bee0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
bef0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
bf00: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
bf10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
bf20: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
bf30: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
bf40: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
bf50: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
bf60: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
bf70: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
bf80: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
bf90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
bfa0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
bfb0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
bfc0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
bfd0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
bfe0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
bff0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
c000: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
c010: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
c020: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
c030: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
c040: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
c050: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
c060: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
c070: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
c080: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
c090: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
c0a0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
c0b0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
c0c0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
c0d0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
c0e0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
c0f0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
c100: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
c110: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
c120: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
c130: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
c140: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
c150: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
c160: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
c170: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c180: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
c190: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c1a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
c1b0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
c1c0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
c1d0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
c1e0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
c1f0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
c200: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
c210: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
c220: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
c230: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
c240: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
c250: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
c260: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c270: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c280: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
c290: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
c2a0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
c2b0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
c2c0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
c2d0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
c2e0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
c2f0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
c300: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
c310: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
c320: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
c330: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
c340: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
c350: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
c360: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
c370: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
c380: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c390: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
c3a0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
c3b0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
c3c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
c3d0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
c3e0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
c3f0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
c400: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
c410: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
c420: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c430: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
c440: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
c450: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
c460: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
c470: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
c480: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
c490: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
c4a0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
c4b0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
c4c0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
c4d0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
c4e0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
c4f0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
c500: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
c510: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
c520: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
c530: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
c540: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
c550: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
c560: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
c570: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
c580: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
c590: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
c5a0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
c5b0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
c5c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c5d0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
c5e0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
c5f0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
c600: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
c610: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
c620: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
c630: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
c640: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
c650: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
c660: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
c670: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
c680: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
c690: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c6a0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
c6b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
c6c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
c6d0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c6e0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c6f0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c700: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c710: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c720: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c730: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c740: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c750: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c760: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c770: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c780: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c790: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c7a0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c7b0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c7c0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c7d0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c7e0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c7f0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c800: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c810: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c820: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c830: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c840: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c850: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c860: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c870: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c880: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c890: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c8a0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c8b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c8c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c8d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c8e0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c8f0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c910: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c920: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c930: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c940: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c950: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c960: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c970: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c980: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c990: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c9a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c9b0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c9c0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c9d0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c9e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c9f0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
ca00: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
ca10: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
ca20: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
ca30: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
ca40: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
ca50: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
ca60: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
ca70: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
ca80: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
ca90: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
caa0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
cab0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
cac0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
cad0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
cae0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
caf0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
cb00: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
cb10: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
cb20: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
cb30: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
cb40: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
cb50: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
cb60: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
cb70: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
cb80: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
cb90: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
cba0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
cbb0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
cbc0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
cbd0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
cbe0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
cbf0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
cc00: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
cc10: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
cc20: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
cc30: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cc40: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cc50: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
cc60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
cc70: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
cc80: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
cc90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cca0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
ccb0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
ccc0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
ccd0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
cce0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
ccf0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cd00: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
cd10: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
cd20: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
cd30: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
cd40: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
cd50: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
cd60: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
cd70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cd80: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
cd90: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
cda0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
cdb0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
cdc0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
cdd0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
cde0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
cdf0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
ce00: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
ce10: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
ce20: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
ce30: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
ce40: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
ce50: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
ce60: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
ce70: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
ce80: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
ce90: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
cea0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
ceb0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
cec0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
ced0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
cee0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
cef0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
cf00: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
cf10: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cf20: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
cf30: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
cf40: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
cf50: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
cf60: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
cf70: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
cf80: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
cf90: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
cfa0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
cfb0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
cfc0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
cfd0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
cfe0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
cff0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
d000: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
d010: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
d020: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
d030: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
d040: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
d050: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
d060: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
d070: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
d080: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
d090: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
d0a0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
d0b0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
d0c0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
d0d0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
d0e0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
d0f0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
d100: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
d110: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
d120: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
d130: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
d140: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
d150: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
d160: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
d170: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
d180: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
d190: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
d1a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
d1b0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
d1c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d1d0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
d1e0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
d1f0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
d200: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d210: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
d220: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d230: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
d240: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
d250: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d260: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
d270: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d280: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
d290: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
d2a0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
d2b0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
d2c0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
d2d0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
d2e0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
d2f0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
d300: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
d310: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
d320: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
d330: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d340: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
d350: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
d360: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
d370: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
d380: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d390: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
d3a0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
d3b0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
d3c0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
d3d0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
d3e0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
d3f0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
d400: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
d410: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
d420: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
d430: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
d440: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
d450: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
d460: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
d470: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d480: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
d490: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
d4a0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
d4b0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
d4c0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
d4d0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
d4e0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
d4f0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
d500: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
d510: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
d520: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
d530: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d540: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
d550: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
d560: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
d570: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
d580: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
d590: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
d5a0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
d5b0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
d5c0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
d5d0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
d5e0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
d5f0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
d600: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
d610: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
d620: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
d630: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
d640: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
d650: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
d660: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
d670: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
d680: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
d690: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
d6a0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
d6b0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
d6c0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
d6d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d6e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d6f0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d700: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d710: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d720: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d730: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d740: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d750: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d760: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d770: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d780: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d790: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d7a0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d7b0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d7c0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d7d0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d7e0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d7f0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d800: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d810: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d820: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d830: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d840: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d850: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d860: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d870: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d880: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d890: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d8a0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d8b0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d8c0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d8d0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d8e0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d8f0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d900: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d910: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d920: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d930: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d940: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d950: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d960: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d970: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d980: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d990: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d9a0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d9b0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d9c0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d9d0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d9e0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d9f0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
da00: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
da10: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
da20: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
da30: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
da40: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
da50: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
da60: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
da70: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
da80: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
da90: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
daa0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
dab0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
dac0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
dad0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
dae0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
daf0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
db00: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
db10: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
db20: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
db30: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
db40: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
db50: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
db60: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
db70: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
db80: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
db90: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
dba0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
dbb0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
dbc0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
dbd0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
dbe0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
dbf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
dc00: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
dc10: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
dc20: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
dc30: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
dc40: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
dc50: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
dc60: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
dc70: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
dc80: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
dc90: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
dca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
dcb0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
dcc0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
dcd0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
dce0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
dcf0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
dd00: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
dd10: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
dd20: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
dd30: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
dd40: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
dd50: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
dd60: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
dd70: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
dd80: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
dd90: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
dda0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ddb0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ddc0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
ddd0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
dde0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
ddf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
de00: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
de10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
de20: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
de30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
de40: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
de50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
de60: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
de70: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
de80: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
de90: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
dea0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
deb0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
dec0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
ded0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
dee0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
def0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
df00: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
df10: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
df20: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
df30: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
df40: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
df50: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
df60: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
df70: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
df80: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
df90: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
dfa0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
dfb0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
dfc0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
dfd0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
dfe0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
dff0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
e000: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
e010: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
e020: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
e030: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e040: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
e050: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
e060: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e070: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
e080: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e090: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e0a0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
e0b0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e0c0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
e0d0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
e0e0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
e0f0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
e100: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
e110: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
e120: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
e130: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
e140: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
e150: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e160: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e170: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
e180: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e190: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
e1a0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
e1b0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
e1c0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
e1d0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
e1e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e1f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e200: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
e210: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
e220: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
e230: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
e240: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e250: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e260: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
e270: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
e280: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e290: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e2a0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
e2b0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e2c0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e2d0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
e2e0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
e2f0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
e300: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
e310: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
e320: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
e330: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
e340: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
e350: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
e360: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
e370: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
e380: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
e390: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
e3a0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e3b0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e3c0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
e3d0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
e3e0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
e3f0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
e400: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
e410: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
e420: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
e430: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
e440: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
e450: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
e460: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
e470: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e480: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
e490: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
e4a0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
e4b0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
e4c0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
e4d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e4e0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
e4f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e500: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
e510: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
e520: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
e530: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
e540: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
e550: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
e560: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
e570: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
e580: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
e590: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
e5a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e5b0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
e5c0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
e5d0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
e5e0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
e5f0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
e600: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
e610: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
e620: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
e630: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
e640: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e650: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
e660: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e670: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e680: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
e690: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
e6a0: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
e6b0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
e6c0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
e6d0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e6e0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e6f0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e700: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e710: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e720: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e730: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e740: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e750: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e760: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e770: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e780: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e790: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e7a0: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e7b0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e7c0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e7d0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e7e0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e7f0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e800: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e810: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e820: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e830: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e840: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e850: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e860: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e870: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e880: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e890: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e8a0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e8b0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e8c0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e8d0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e8e0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e8f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e900: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e910: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e920: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e930: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e940: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e950: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e960: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e970: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e980: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e990: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e9a0: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e9b0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e9c0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e9d0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e9e0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e9f0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
ea00: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ea10: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
ea20: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
ea30: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
ea40: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
ea50: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
ea60: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
ea70: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
ea80: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
ea90: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
eaa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
eab0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
eac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ead0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
eae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eaf0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
eb00: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
eb10: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
eb20: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
eb30: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
eb40: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
eb50: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
eb60: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
eb70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
eb80: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
eb90: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
eba0: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
ebb0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
ebc0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
ebd0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
ebe0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
ebf0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
ec00: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
ec10: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
ec20: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
ec30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
ec40: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
ec50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
ec60: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
ec70: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
ec80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
ec90: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
eca0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
ecb0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
ecc0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
ecd0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
ece0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
ecf0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
ed00: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
ed10: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ed20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ed30: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ed40: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ed50: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ed60: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ed70: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
ed80: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
ed90: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
eda0: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
edb0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
edc0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
edd0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ede0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
edf0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ee00: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ee10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ee20: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ee30: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ee40: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ee50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee60: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ee70: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
ee80: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
ee90: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
eea0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
eeb0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
eec0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
eed0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
eee0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
eef0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
ef00: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
ef10: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
ef20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ef30: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
ef40: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
ef50: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
ef60: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ef70: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ef80: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ef90: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
efa0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
efb0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
efc0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
efd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
efe0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
eff0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f000: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
f010: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
f020: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f030: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
f040: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
f050: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
f060: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
f070: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f080: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
f090: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
f0a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f0b0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
f0c0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
f0d0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
f0e0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
f0f0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
f100: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
f110: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
f120: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
f130: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
f140: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
f150: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f160: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
f170: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
f180: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
f190: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
f1a0: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
f1b0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
f1c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f1d0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
f1e0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
f1f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f200: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
f210: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f220: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
f230: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
f240: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
f250: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
f260: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
f270: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f280: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
f290: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f2a0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
f2b0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
f2c0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
f2d0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
f2e0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
f2f0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
f300: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
f310: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
f320: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
f330: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
f340: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
f350: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
f360: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
f370: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
f380: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f390: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f3a0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
f3b0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
f3c0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
f3d0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
f3e0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
f3f0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
f400: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
f410: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f420: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f430: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
f440: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
f450: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
f460: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f470: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
f480: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
f490: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
f4a0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
f4b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
f4c0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
f4d0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
f4e0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
f4f0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
f500: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
f510: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
f520: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
f530: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
f540: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
f550: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
f560: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
f570: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
f580: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
f590: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
f5a0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
f5b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f5c0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
f5d0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f5e0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f5f0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
f600: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
f610: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
f620: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
f630: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
f640: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f650: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f660: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
f670: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f680: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f690: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
f6a0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
f6b0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
f6c0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
f6d0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f6e0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f6f0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f700: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f710: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f720: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f730: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f740: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f750: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f760: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f770: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f780: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f790: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f7a0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f7b0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f7c0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f7d0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f7e0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f7f0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f800: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f810: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f820: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f830: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f840: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f850: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f860: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f870: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f880: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f890: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f8a0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f8b0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f8c0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f8d0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f8e0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f8f0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f900: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f910: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f920: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f930: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f940: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f950: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f960: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f970: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f980: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f990: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f9a0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f9b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f9c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f9d0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f9e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f9f0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
fa00: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
fa10: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
fa20: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
fa30: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fa40: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
fa50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fa60: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
fa70: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
fa80: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
fa90: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
faa0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fab0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
fac0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
fad0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
fae0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
faf0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
fb00: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
fb10: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
fb20: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
fb30: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
fb40: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
fb50: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
fb60: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
fb70: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
fb80: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
fb90: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
fba0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fbb0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fbc0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
fbd0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
fbe0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
fbf0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
fc00: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
fc10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fc20: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
fc30: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fc40: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
fc50: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
fc60: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
fc70: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
fc80: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
fc90: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
fca0: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
fcb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fcc0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fcd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
fce0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fcf0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
fd00: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
fd10: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
fd20: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fd30: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
fd40: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
fd50: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
fd60: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
fd70: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
fd80: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
fd90: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
fda0: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
fdb0: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
fdc0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fdd0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fde0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
fdf0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
fe00: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
fe10: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
fe20: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
fe30: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
fe40: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
fe50: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
fe60: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
fe70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fe80: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fe90: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
fea0: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
feb0: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
fec0: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
fed0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fee0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
fef0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
ff00: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
ff10: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
ff20: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
ff30: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
ff40: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
ff50: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
ff60: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
ff70: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
ff80: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
ff90: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
ffa0: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
ffb0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
ffc0: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
ffd0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ffe0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
fff0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10000 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10020 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10030 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
10040 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
10050 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
10060 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
10070 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
10080 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
10090 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
100a0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
100b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
100c0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
100d0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
100e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
100f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10100 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10110 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10120 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10130 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10140 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10150 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10160 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10170 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10180 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10190 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
101a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
101b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
101c0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
101d0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
101e0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
101f0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10200 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10210 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10220 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10230 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10240 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10250 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10260 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10270 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10280 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10290 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
102a0 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
102b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
102c0 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
102d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
102e0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
102f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10300 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10310 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
10320 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10330 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10350 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
10360 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10370 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10380 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10390 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
103a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
103b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
103c0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
103d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
103e0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
103f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10400 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
10410 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
10420 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10430 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10440 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10450 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
10460 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10470 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10480 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10490 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
104a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
104b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
104c0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
104d0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
104e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
104f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10500 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
10510 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10520 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10530 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10540 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10550 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10560 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10570 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10580 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10590 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
105a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
105b0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
105c0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
105d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
105e0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
105f0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10600 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
10610 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
10620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10630 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10640 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10650 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10660 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10670 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10680 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10690 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
106a0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
106b0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
106c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
106d0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
106e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
106f0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10700 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
10710 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
10720 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10730 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10740 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10750 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10760 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10770 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10780 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10790 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
107a0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
107b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
107c0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
107d0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
107e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
107f0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10800 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
10810 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
10820 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10830 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10840 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10850 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10860 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10870 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10880 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10890 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
108a0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
108b0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
108c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
108d0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
108e0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
108f0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10900 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10910 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
10920 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10930 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10940 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10950 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10960 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10970 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10980 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10990 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
109a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
109b0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
109c0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
109d0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
109e0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
109f0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10a00 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
10a10 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
10a20 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10a40 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10a50 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10a60 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10a70 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10a80 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10a90 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10aa0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10ab0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10ac0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
10ad0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
10ae0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10af0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
10b00 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
10b10 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
10b20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
10b30 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
10b40 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
10b50 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
10b60 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10b70 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10b80 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10b90 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10ba0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
10bb0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
10bc0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
10bd0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
10be0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
10bf0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
10c00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10c10 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10c20 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10c30 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10c40 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10c50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10c60 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10c70 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10c80 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10c90 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10ca0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
10cb0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
10cc0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
10cd0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
10ce0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
10cf0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
10d00 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10d10 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10d20 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10d30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10d40 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10d50 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10d60 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10d70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10d80 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10d90 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10da0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
10db0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
10dc0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
10dd0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
10de0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
10df0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
10e00 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10e10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10e20 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
10e30 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
10e40 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
10e50 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
10e60 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
10e70 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
10e80 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
10e90 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10ea0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10eb0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10ec0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ed0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10ee0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10ef0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10f00 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10f10 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10f20 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10f30 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
10f40 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
10f50 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
10f60 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
10f70 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10f80 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
10f90 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10fa0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10fb0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10fc0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10fd0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10fe0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10ff0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11000 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11010 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11020 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11030 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11040 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11050 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11060 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11070 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11080 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11090 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
110a0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
110b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
110c0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
110d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
110e0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
110f0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11100 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11110 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11120 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11130 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11140 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11160 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11170 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11180 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11190 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
111a0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
111b0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
111c0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
111d0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
111e0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
111f0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11200 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11210 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11220 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11230 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11240 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11250 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11260 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11270 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11280 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11290 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
112a0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
112b0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
112c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
112d0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
112e0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
112f0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11300 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
11310 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
11320 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11330 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11340 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11350 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11360 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11370 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11380 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11390 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
113a0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
113b0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
113c0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
113d0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
113e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
113f0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11400 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11410 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
11420 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11430 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11440 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11450 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
11460 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11470 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11480 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
114a0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
114b0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
114c0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
114d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
114e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
114f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11500 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
11510 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
11520 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11530 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11540 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11550 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11560 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11570 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11580 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11590 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
115a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
115b0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
115c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
115d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
115e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
115f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11600 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
11610 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
11620 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11630 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11640 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11650 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11660 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11670 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11680 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11690 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
116a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
116b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
116c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
116d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
116e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
116f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11700 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11710 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11720 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11730 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11740 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11750 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11770 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11780 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11790 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
117a0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
117b0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
117c0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
117d0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
117e0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
117f0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11800 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11810 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11820 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11830 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11840 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11850 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11860 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11870 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11880 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11890 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
118a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
118b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
118c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
118d0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
118e0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
118f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11900 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11910 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11920 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11930 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11940 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11950 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11960 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11970 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11980 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11990 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
119a0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
119b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
119c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
119d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
119e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
119f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11a00 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11a10 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11a20 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11a30 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11a40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11a50 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11a60 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11a70 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11a80 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11aa0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11ab0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11ac0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11ad0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11ae0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11af0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
11b00 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11b10 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11b30 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
11b40 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
11b50 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
11b60 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
11b70 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
11b80 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
11b90 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11ba0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11bb0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11bc0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11bd0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11be0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11bf0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11c00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11c10 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11c20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11c30 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11c40 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11c50 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11c60 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11c70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11c80 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
11c90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11ca0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11cb0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11cc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11cd0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11ce0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11cf0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11d00 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11d10 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11d20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11d30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11d40 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11d50 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11d60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11d70 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11d80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11d90 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11da0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11db0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11dc0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11dd0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11de0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11df0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11e00 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11e10 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11e20 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11e40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11e50 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11e60 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
11e70 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
11e80 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
11e90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11ea0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11eb0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11ec0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11ed0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11ee0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11ef0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11f00 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11f10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11f20 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11f30 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
11f40 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
11f50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11f60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
11f70 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
11f80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11f90 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11fa0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11fb0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11fc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11fd0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11fe0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11ff0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12000 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12010 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12020 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12030 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12040 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12050 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12070 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12080 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12090 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
120a0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
120b0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
120c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
120d0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
120e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
120f0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12100 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12110 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12120 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12130 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12140 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
12160 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12170 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12180 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12190 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
121a0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
121b0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
121c0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
121d0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
121e0 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
121f0 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12200 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12210 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
12220 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
12230 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
12240 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
12250 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
12260 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12270 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12280 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12290 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
122a0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
122b0 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
122c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
122d0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
122e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
122f0 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
12300 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12310 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12320 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12330 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
12340 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
12350 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12360 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12370 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12380 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12390 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
123a0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
123b0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
123c0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
123d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
123e0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
123f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12400 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12410 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12420 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
12430 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
12440 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
12450 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
12460 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
12470 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
12480 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12490 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
124a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
124b0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
124c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
124d0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
124e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
124f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
12500 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
12510 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
12520 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
12530 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
12540 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
12550 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
12560 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
12570 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
12580 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
12590 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
125a0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
125b0 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
125c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
125d0 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
125e0 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
125f0 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
12600 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12610 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
12620 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12630 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
12640 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
12650 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
12660 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
12670 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12680 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
12690 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
126a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
126b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
126c0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
126d0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
126e0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
126f0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12700 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12710 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
12720 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12730 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12740 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
12750 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
12760 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12770 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12780 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12790 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
127a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
127b0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
127c0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
127d0 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
127e0 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
127f0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12800 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
12810 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
12820 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
12830 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
12840 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
12850 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
12860 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
12870 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
12880 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12890 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
128a0 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
128b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
128c0 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
128d0 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
128e0 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
128f0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
12900 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
12910 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12920 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12930 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12940 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
12950 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
12960 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12970 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
12980 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
12990 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
129a0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
129b0 20 74 68 72 65 61 64 20 61 6e 64 20 6e 6f 74 0a   thread and not.
129c0 2a 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  ** more than one
129d0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
129e0 70 65 72 20 74 68 72 65 61 64 20 77 68 65 6e 20  per thread when 
129f0 6e 6f 74 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  not performing.*
12a00 2a 20 61 20 5b 63 68 65 63 6b 70 6f 69 6e 74 5d  * a [checkpoint]
12a10 20 69 6e 20 5b 57 41 4c 20 6d 6f 64 65 5d 2e 0a   in [WAL mode]..
12a20 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12a30 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
12a40 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12a50 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
12a60 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
12a70 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
12a80 7a 65 2c 20 65 78 63 65 70 74 20 77 68 65 6e 20  ze, except when 
12a90 70 65 72 66 6f 72 6d 69 6e 67 20 61 20 5b 63 68  performing a [ch
12aa0 65 63 6b 70 6f 69 6e 74 5d 0a 2a 2a 20 69 6e 20  eckpoint].** in 
12ab0 5b 57 41 4c 20 6d 6f 64 65 5d 20 77 68 65 6e 20  [WAL mode] when 
12ac0 74 68 65 20 73 63 72 61 74 63 68 20 62 75 66 66  the scratch buff
12ad0 65 72 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  er request size 
12ae0 69 73 20 61 20 73 6d 61 6c 6c 20 66 72 61 63 74  is a small fract
12af0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 73 69  ion.** of the si
12b00 7a 65 20 6f 66 20 74 68 65 20 57 41 4c 20 66 69  ze of the WAL fi
12b10 6c 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  le..** ^If SQLit
12b20 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12b30 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12b40 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12b50 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12b60 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12b70 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12b80 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12b90 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12ba0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12bb0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12bc0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
12bd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12be0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
12bf0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12c00 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12c10 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12c20 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12c30 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12c40 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12c50 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12c60 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12c70 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
12c80 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
12c90 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12ca0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
12cb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12cc0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12cd0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12ce0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
12cf0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12d00 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
12d10 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
12d20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
12d30 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
12d40 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12d50 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12d60 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
12d70 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
12d80 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
12d90 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
12da0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
12db0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
12dc0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
12dd0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
12de0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
12df0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
12e00 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
12e10 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
12e20 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
12e30 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
12e40 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
12e50 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
12e60 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
12e70 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
12e80 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
12e90 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
12ea0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
12eb0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
12ec0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
12ed0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
12ee0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
12ef0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
12f00 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
12f10 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
12f20 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
12f30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
12f40 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12f50 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12f60 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12f70 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12f80 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
12f90 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
12fa0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
12fb0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
12fc0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
12fd0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
12fe0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
12ff0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
13000 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
13010 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
13020 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
13030 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
13040 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
13050 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
13060 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
13070 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
13080 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
13090 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
130a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
130b0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
130c0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
130d0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
130e0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
130f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
13100 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
13110 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13120 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
13130 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13140 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
13150 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
13160 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13170 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13180 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
13190 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
131a0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
131b0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
131c0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
131d0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
131e0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
131f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13200 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
13210 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
13220 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
13230 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
13240 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
13250 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
13260 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
13270 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
13280 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
13290 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
132a0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
132b0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
132c0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
132d0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
132e0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
132f0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
13300 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
13310 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
13320 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
13330 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
13340 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
13350 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
13360 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
13370 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
13380 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
13390 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
133a0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
133b0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
133c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
133d0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
133e0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
133f0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
13400 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
13410 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
13420 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
13430 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
13440 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
13450 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13460 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
13470 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13480 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13490 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
134a0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
134b0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
134c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
134d0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
134e0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
134f0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
13500 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
13510 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
13520 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
13530 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
13540 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13550 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
13560 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
13570 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13580 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
13590 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
135a0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
135b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
135c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
135d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
135e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
135f0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
13600 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13610 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13620 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
13630 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
13640 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
13650 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
13660 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13670 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
13680 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13690 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
136a0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
136b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
136c0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
136d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
136e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
136f0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
13700 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
13710 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13720 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13730 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13740 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13750 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13760 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13770 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13780 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13790 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
137a0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
137b0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
137c0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
137d0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
137e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
137f0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
13800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13810 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13820 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13830 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13840 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13860 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13880 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13890 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
138a0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
138b0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
138c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
138d0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
138e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
138f0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13900 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
13910 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
13920 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13930 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13940 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13950 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
13960 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
13970 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13980 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13990 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
139a0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
139b0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
139c0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
139d0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
139e0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
139f0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
13a00 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
13a10 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
13a20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13a30 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13a40 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13a50 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13a60 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13a70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13a80 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
13a90 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
13aa0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
13ab0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
13ac0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
13ad0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13ae0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
13af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13b00 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
13b10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13b20 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13b30 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13b40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13b50 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13b60 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13b70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13b80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13b90 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13ba0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
13bb0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
13bc0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
13bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13be0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
13bf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13c00 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
13c10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13c20 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
13c30 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13c40 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13c50 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13c60 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
13c70 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
13c80 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
13c90 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
13ca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13cb0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
13cc0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13cd0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
13ce0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
13cf0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
13d00 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13d10 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
13d20 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13d30 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
13d40 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13d50 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
13d60 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
13d70 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
13d80 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13d90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13da0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
13db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13dc0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13dd0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13de0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13df0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13e00 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
13e10 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
13e20 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
13e30 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13e40 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
13e50 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
13e60 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
13e70 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13e80 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
13e90 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
13ea0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
13eb0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
13ec0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
13ed0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
13ee0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13ef0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13f00 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13f10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13f20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13f30 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13f40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13f50 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13f60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
13f70 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13f80 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13f90 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
13fa0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
13fb0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
13fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
13fd0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
13fe0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14000 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14010 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
14020 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14030 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14040 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
14050 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14060 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
14070 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
14080 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14090 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
140a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
140b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
140c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
140d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
140e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
140f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14100 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
14110 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
14120 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
14130 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14140 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
14150 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14160 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
14170 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
14180 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14190 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
141a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
141b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
141c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
141d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
141e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
141f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
14200 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14210 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14220 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14230 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
14240 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14250 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14260 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14270 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14280 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14290 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
142a0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
142b0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
142c0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
142d0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
142e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
142f0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
14300 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
14310 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
14320 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14330 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14340 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14350 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14360 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14370 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14380 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14390 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
143a0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
143b0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
143c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
143d0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
143e0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
143f0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
14400 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14410 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
14420 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14430 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14440 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14450 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14460 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14470 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14480 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14490 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
144a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
144b0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
144c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
144d0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
144e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
144f0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
14500 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
14510 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14520 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
14530 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
14540 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
14550 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
14560 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
14570 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
14580 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14590 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
145a0 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
145b0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
145c0 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
145d0 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
145e0 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
145f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
14600 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
14610 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
14620 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
14630 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
14640 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
14650 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
14660 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
14670 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
14680 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14690 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
146a0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
146b0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
146c0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
146d0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
146e0 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
146f0 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
14700 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
14710 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14720 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
14730 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
14740 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
14750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14760 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14770 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
14780 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14790 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
147a0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
147b0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
147c0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
147d0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
147e0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
147f0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
14800 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14810 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
14820 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
14830 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
14840 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14850 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20  AN.** <dd>^This 
14860 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14870 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72  ingle integer ar
14880 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14890 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a  interpreted as.*
148a0 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  * a boolean in o
148b0 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
148c0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  r disable the us
148d0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
148e0 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c  dices for.** ful
148f0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
14900 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
14910 69 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61  izer.  ^The defa
14920 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
14930 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
14940 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
14950 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
14960 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
14970 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
14980 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
14990 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
149a0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
149b0 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
149c0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
149d0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
149e0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
149f0 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
14a00 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
14a10 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
14a20 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
14a30 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
14a40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
14a50 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14a60 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
14a70 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
14a80 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
14a90 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
14aa0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
14ab0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
14ac0 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
14ad0 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
14ae0 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
14af0 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
14b00 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
14b10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14b20 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
14b30 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14b40 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14b60 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
14b70 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
14b80 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
14b90 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
14ba0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
14bb0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
14bc0 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
14bd0 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
14be0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
14bf0 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
14c00 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
14c10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14c20 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
14c30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14c40 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
14c50 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
14c60 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
14c70 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
14c80 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
14c90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
14ca0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
14cb0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
14cc0 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
14cd0 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
14ce0 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
14cf0 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
14d00 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
14d10 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
14d20 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
14d30 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
14d40 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
14d50 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
14d60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
14d70 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
14d80 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
14d90 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
14da0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
14db0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
14dc0 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
14dd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
14de0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
14df0 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
14e00 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
14e20 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14e30 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
14e40 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
14e50 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
14e60 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
14e70 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
14e80 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
14e90 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
14ea0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
14eb0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
14ec0 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
14ed0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14ee0 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
14ef0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
14f00 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
14f10 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
14f20 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
14f30 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14f40 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
14f50 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
14f60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
14f70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
14f80 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
14f90 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
14fa0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
14fb0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
14fc0 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
14fd0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
14fe0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14ff0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15000 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15010 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15020 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15030 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15040 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15050 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15060 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15070 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15080 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15090 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
150a0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
150b0 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
150c0 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
150d0 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
150e0 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
150f0 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
15100 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
15110 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15120 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15130 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15140 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15150 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15160 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15170 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15180 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15190 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
151a0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
151b0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
151c0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
151d0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
151e0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
151f0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
15200 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
15210 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
15220 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15230 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  size.** cannot b
15240 65 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e  e changed at run
15250 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20  -time.  Nor may 
15260 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
15270 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
15280 20 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70   exceed the comp
15290 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
152a0 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
152b0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
152c0 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
152d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
152e0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
152f0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
15300 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
15310 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
15320 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
15330 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
15340 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
15350 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
15360 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15370 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
15380 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15390 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
153a0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20  ZE.** <dd>^This 
153b0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
153c0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
153d0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  te is compiled f
153e0 6f 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69  or Windows.** wi
153f0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
15400 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
15410 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15420 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c   defined..** SQL
15430 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15440 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20  _HEAPSIZE takes 
15450 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 32-bit unsigne
15460 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a  d integer value.
15470 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65  ** that specifie
15480 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  s the maximum si
15490 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65  ze of the create
154a0 64 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e  d heap..** </dl>
154b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
154c0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
154d0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
154e0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
154f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
15500 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
15510 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
15520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
15530 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
15540 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15560 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
15570 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
15580 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
15590 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
155a0 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
155b0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
155c0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
155d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
155e0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
155f0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
15600 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
15610 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15620 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
15630 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
15640 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
15650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15660 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
15670 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
15680 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
15690 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
156a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
156b0 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
156c0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
156d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
156e0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
156f0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
15700 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
15710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15720 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
15730 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
15740 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15750 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
15760 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
15770 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
15780 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
15790 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
157a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
157b0 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
157c0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
157d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
157e0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
157f0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
15800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15810 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
15820 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
15830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15840 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
15850 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
15860 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
15870 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15880 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
15890 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
158a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
158b0 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
158c0 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
158d0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
158e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
158f0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15900 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
15910 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15920 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15940 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15950 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
15960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15970 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
15980 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
15990 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
159a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
159b0 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
159c0 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
159d0 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
159e0 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
159f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15a00 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
15a10 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
15a20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
15a30 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
15a40 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
15a50 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
15a60 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
15a70 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
15a80 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
15a90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15aa0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
15ab0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
15ac0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15ad0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
15ae0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
15af0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
15b00 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
15b10 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
15b20 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
15b30 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
15b40 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
15b50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15b60 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
15b70 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
15b80 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
15b90 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
15ba0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
15bb0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15bc0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
15bd0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
15be0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
15bf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
15c00 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
15c10 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
15c20 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
15c30 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
15c40 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
15c50 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
15c60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
15c70 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
15c80 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
15c90 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15ca0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
15cb0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15cc0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
15cd0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
15ce0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15cf0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
15d00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
15d10 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
15d20 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
15d30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15d40 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
15d50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
15d60 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15d70 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
15d80 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
15d90 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15da0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
15db0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
15dc0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
15dd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15de0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
15df0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15e00 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
15e10 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
15e20 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
15e30 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
15e40 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
15e50 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
15e60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
15e70 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
15e80 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
15e90 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
15ea0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
15eb0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
15ec0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
15ed0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
15ee0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
15ef0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
15f00 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
15f10 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
15f20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
15f30 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
15f40 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
15f50 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
15f60 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
15f70 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
15f80 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
15f90 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
15fa0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
15fb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
15fc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15fd0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
15fe0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
15ff0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16000 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16010 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16020 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16030 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16040 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16060 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16070 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16080 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16090 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
160a0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
160b0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
160c0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
160d0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
160e0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
160f0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16100 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16110 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16120 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16130 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16140 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16150 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16160 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16170 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16180 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16190 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
161a0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
161b0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
161c0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
161d0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
161e0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
161f0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16200 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16210 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16220 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16230 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16240 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16250 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16260 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16270 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16280 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16290 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
162a0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
162b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
162c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
162d0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
162e0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
162f0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
16300 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
16310 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
16320 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
16330 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
16340 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
16350 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16360 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16370 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16380 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16390 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
163a0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
163b0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
163c0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
163d0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
163e0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
163f0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
16400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
16410 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
16420 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
16430 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
16440 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
16450 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16460 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16470 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16480 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
16490 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
164a0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
164b0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
164c0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
164d0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
164e0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
164f0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16500 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
16510 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
16520 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
16530 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
16540 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
16550 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
16560 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
16570 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
16580 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
16590 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
165a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
165b0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
165c0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
165d0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
165e0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
165f0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
16600 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
16610 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
16620 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
16630 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16640 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
16650 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16660 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16670 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
16680 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16690 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
166a0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
166b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
166c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
166d0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
166e0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
166f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16700 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16710 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
16720 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
16730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16740 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
16750 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
16760 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
16770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
16780 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
16790 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
167a0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
167b0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
167c0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
167d0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
167e0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
167f0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16800 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
16810 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
16820 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
16830 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
16840 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
16850 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
16860 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
16870 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
16880 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
16890 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
168a0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
168b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
168c0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
168d0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
168e0 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
168f0 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
16900 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
16910 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
16920 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
16930 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
16940 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
16950 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
16960 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
16970 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
16980 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
16990 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
169a0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
169b0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
169c0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
169d0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
169e0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
169f0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
16a00 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
16a10 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
16a20 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
16a30 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
16a40 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
16a50 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
16a60 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
16a70 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
16a80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
16a90 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
16aa0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
16ab0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
16ac0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
16ad0 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
16ae0 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
16af0 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
16b00 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
16b10 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
16b20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
16b30 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
16b40 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16b50 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
16b60 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
16b70 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
16b80 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
16b90 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
16ba0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
16bb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
16bc0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
16bd0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
16be0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16bf0 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
16c00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
16c10 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
16c20 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
16c30 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
16c40 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
16c50 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
16c60 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
16c70 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
16c80 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
16c90 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
16ca0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
16cb0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16cc0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
16cd0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
16ce0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
16cf0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
16d00 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
16d10 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
16d20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
16d30 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
16d40 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
16d50 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16d60 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
16d70 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
16d80 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
16d90 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
16da0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
16db0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
16dc0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
16dd0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
16de0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
16df0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16e00 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
16e10 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
16e20 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
16e30 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
16e40 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
16e50 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
16e60 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
16e70 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
16e80 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
16e90 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
16ea0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
16eb0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
16ec0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
16ed0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
16ee0 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
16ef0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
16f00 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
16f10 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
16f20 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
16f30 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
16f40 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
16f50 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
16f60 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
16f70 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
16f80 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
16f90 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
16fa0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16fb0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
16fc0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
16fd0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
16fe0 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
16ff0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
17000 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
17010 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
17020 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
17030 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
17040 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
17050 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
17060 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
17070 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
17080 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17090 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
170a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
170b0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
170c0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
170d0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
170e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
170f0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
17100 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
17110 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
17120 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
17130 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
17140 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
17150 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
17160 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
17170 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
17180 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17190 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
171a0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
171b0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
171c0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
171d0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
171e0 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
171f0 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
17200 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
17210 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17220 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
17230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17240 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
17250 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
17260 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17270 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17280 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
17290 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
172a0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
172b0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
172c0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
172d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
172e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
172f0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
17300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17310 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
17320 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
17330 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
17340 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
17350 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
17360 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
17370 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
17380 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
17390 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
173a0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
173b0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
173c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
173d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
173e0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
173f0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
17400 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
17410 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
17420 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
17430 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
17440 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
17450 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
17460 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
17470 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
17480 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
17490 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
174a0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
174b0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
174c0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
174d0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
174e0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
174f0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
17500 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
17510 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
17520 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
17530 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
17540 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
17550 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
17560 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
17570 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
17580 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
17590 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
175a0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
175b0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
175c0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
175d0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
175e0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
175f0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
17600 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
17610 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
17620 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
17630 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
17640 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
17650 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
17660 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
17670 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
17680 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
17690 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
176a0 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
176b0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
176c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
176d0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
176e0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
176f0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
17700 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
17710 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
17720 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
17730 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
17740 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
17750 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
17760 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
17770 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
17780 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
17790 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
177a0 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
177b0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
177c0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
177d0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
177e0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
177f0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
17800 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17810 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
17820 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
17830 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
17840 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
17850 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
17860 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
17870 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
17880 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
17890 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
178a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
178b0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
178c0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
178d0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
178e0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
178f0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
17900 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
17910 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
17920 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
17930 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
17940 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
17950 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
17960 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
17970 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
17980 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
17990 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
179a0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
179b0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
179c0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
179d0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
179e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
179f0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
17a00 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
17a10 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
17a20 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
17a30 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
17a40 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17a50 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
17a60 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
17a70 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
17a80 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
17a90 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
17aa0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
17ab0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
17ac0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
17ad0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17ae0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17af0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17b00 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17b10 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17b20 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17b30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17b40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17b50 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17b60 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17b70 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17b80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17b90 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17ba0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17bb0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17bc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17bd0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17be0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17bf0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17c00 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17c10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17c20 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17c30 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17c40 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17c50 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17c60 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
17c70 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
17c80 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
17c90 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
17ca0 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
17cb0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
17cc0 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
17cd0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
17ce0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17cf0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
17d00 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
17d10 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
17d20 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
17d30 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
17d40 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
17d50 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
17d60 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
17d70 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
17d80 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
17d90 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17da0 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
17db0 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
17dc0 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
17dd0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
17de0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
17df0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
17e00 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
17e10 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
17e20 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
17e30 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
17e40 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
17e50 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
17e60 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
17e70 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
17e80 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
17e90 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
17ea0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
17eb0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17ec0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17ed0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17ee0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
17ef0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
17f00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
17f10 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
17f20 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
17f30 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
17f40 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
17f50 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
17f60 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
17f70 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17f80 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17f90 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
17fa0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17fb0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17fc0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
17fd0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17fe0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
18000 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
18010 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
18020 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18030 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
18040 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
18050 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
18060 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
18070 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
18080 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
18090 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
180a0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
180b0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
180c0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
180d0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
180e0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
180f0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
18100 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
18110 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
18120 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
18130 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
18140 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
18150 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
18160 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
18170 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
18180 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
18190 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
181a0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
181b0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
181c0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
181d0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
181e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
181f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18200 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
18210 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
18220 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
18230 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18240 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18250 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
18260 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
18270 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
18280 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
18290 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
182a0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
182b0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
182c0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
182d0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
182e0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
182f0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
18300 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
18310 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
18320 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
18330 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
18340 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
18350 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
18360 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
18370 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18380 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
18390 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
183a0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
183b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
183c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
183d0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
183e0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
183f0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
18400 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
18410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
18420 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
18430 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
18440 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
18450 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
18460 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
18470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18480 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
18490 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
184a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
184b0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
184c0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
184d0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
184e0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
184f0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
18500 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
18510 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
18520 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
18530 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
18540 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
18550 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18560 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
18570 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
18580 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
18590 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
185a0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
185b0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
185c0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
185d0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
185e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
185f0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
18600 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18610 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
18620 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
18630 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
18640 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
18650 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
18660 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
18670 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18680 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18690 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
186a0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
186b0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
186c0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
186d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
186e0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
186f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
18700 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
18710 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
18720 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
18730 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
18740 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
18750 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18760 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
18770 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
18780 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
18790 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
187a0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
187b0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
187c0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
187d0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
187e0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
187f0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
18800 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
18810 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
18820 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
18830 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
18840 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
18850 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
18860 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
18870 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
18880 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18890 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
188a0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
188b0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
188c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
188d0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
188e0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
188f0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
18900 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
18910 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
18920 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
18930 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
18940 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
18950 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
18960 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
18970 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
18980 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
18990 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
189a0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
189b0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
189c0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
189d0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
189e0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
189f0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
18a00 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
18a10 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
18a20 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
18a30 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
18a40 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
18a50 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
18a60 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
18a70 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
18a80 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
18a90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
18aa0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18ab0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
18ac0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
18ad0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
18ae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
18af0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
18b00 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
18b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
18b20 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
18b30 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
18b40 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
18b50 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
18b60 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
18b70 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
18b80 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
18b90 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
18ba0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
18bb0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
18bc0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
18bd0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
18be0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18bf0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
18c00 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
18c10 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
18c20 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
18c30 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
18c40 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
18c50 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
18c60 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
18c70 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
18c80 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18c90 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
18ca0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
18cb0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
18cc0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
18cd0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
18ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
18cf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
18d00 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
18d10 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
18d20 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
18d30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
18d40 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
18d50 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
18d60 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18d70 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
18d80 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
18d90 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
18da0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
18db0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
18dc0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
18dd0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18de0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
18df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18e00 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
18e10 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
18e20 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
18e30 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ors.**.** ^The s
18e40 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18e50 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
18e60 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
18e70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
18e80 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
18e90 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
18ea0 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
18eb0 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
18ec0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
18ed0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18ee0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
18ef0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18f00 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
18f10 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
18f20 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
18f30 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
18f40 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
18f50 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18f60 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
18f70 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
18f80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
18f90 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
18fa0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
18fb0 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
18fc0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
18fd0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
18fe0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
18ff0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
19000 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
19010 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
19020 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
19030 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
19040 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
19050 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
19060 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
19070 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
19080 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
19090 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
190a0 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
190b0 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
190c0 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
190d0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
190e0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
190f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
19100 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
19110 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19120 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
19130 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
19140 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
19150 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
19160 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
19170 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
19180 65 64 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ed for the same 
19190 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
191a0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
191b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
191c0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
191d0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
191e0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
191f0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19200 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
19210 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
19220 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
19230 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
19240 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19250 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
19260 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
19270 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
19280 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19290 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
192a0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
192b0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
192c0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
192d0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
192e0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
192f0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
19300 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
19310 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
19320 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
19330 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
19340 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
19350 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
19360 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
19370 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
19380 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
19390 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
193a0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
193b0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
193c0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
193d0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
193e0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
193f0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
19400 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19410 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
19420 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
19430 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19440 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
19450 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
19460 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
19470 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
19480 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
19490 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
194a0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
194b0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
194c0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
194d0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
194e0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
194f0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
19500 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
19510 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
19520 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
19530 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19540 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
19550 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
19560 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
19570 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
19580 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
19590 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
195a0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
195b0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
195c0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
195d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
195e0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
195f0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
19600 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
19610 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
19620 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
19630 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
19640 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
19650 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
19660 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
19670 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
19680 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19690 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
196a0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
196b0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
196c0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
196d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
196e0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
196f0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
19700 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
19710 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
19720 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
19730 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
19740 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
19750 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
19760 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
19770 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
19780 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
19790 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
197a0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
197b0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
197c0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
197d0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
197e0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
197f0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
19800 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
19810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19820 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19830 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19840 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
19850 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
19860 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
19870 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
19880 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
19890 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
198a0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
198b0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
198c0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
198d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
198e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
198f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
19900 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
19910 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19920 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
19930 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
19940 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
19950 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
19960 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19970 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
19980 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
19990 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
199a0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
199b0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
199c0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
199d0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
199e0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
199f0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
19a00 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
19a10 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
19a20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
19a30 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
19a40 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
19a50 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
19a60 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
19a70 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
19a80 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
19a90 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19aa0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
19ab0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
19ac0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
19ad0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
19ae0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
19af0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
19b00 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
19b10 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
19b20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
19b30 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
19b40 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
19b50 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
19b60 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
19b70 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
19b80 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
19b90 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
19ba0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
19bb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19bc0 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
19bd0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
19be0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
19bf0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
19c00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
19c10 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
19c20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
19c30 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
19c40 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
19c50 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
19c60 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
19c70 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
19c80 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
19c90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
19ca0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
19cb0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
19cc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19cd0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
19ce0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
19cf0 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
19d00 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
19d10 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
19d20 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
19d30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
19d40 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
19d50 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19d60 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
19d70 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
19d80 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
19d90 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
19da0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
19db0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
19dc0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19dd0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
19de0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
19df0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
19e00 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
19e10 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
19e20 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
19e30 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
19e40 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
19e50 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
19e60 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
19e70 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
19e80 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
19e90 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
19ea0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
19eb0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
19ec0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
19ed0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
19ee0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
19ef0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
19f00 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
19f10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
19f20 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
19f30 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
19f40 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
19f50 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
19f60 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
19f70 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
19f80 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
19f90 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
19fa0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
19fb0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
19fc0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
19fd0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
19fe0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
19ff0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1a000 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1a010 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1a020 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1a030 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1a040 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1a050 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1a060 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1a070 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1a080 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1a090 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1a0a0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1a0b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1a0d0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1a0e0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1a0f0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1a100 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1a110 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1a120 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1a130 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1a140 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1a150 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1a160 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a170 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1a180 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1a190 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a1a0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1a1b0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1a1c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a1d0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1a1e0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1a1f0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1a200 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a210 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a220 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1a230 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1a240 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a250 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1a260 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1a270 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1a280 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1a290 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1a2a0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1a2b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1a2c0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1a2d0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1a2e0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1a2f0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1a300 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1a310 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1a320 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1a330 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1a340 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1a350 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1a360 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1a370 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1a380 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1a390 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a3a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a3b0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1a3c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a3d0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1a3e0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1a3f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1a400 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1a410 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a420 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1a430 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a440 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1a450 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a460 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1a470 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a480 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1a490 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1a4a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1a4b0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1a4c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1a4d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1a4e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a4f0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1a500 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1a510 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1a520 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1a530 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1a540 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a550 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1a560 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1a570 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1a580 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1a590 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1a5a0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1a5b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1a5c0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1a5d0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1a5e0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1a5f0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1a600 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1a610 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1a620 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1a630 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1a640 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1a650 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1a660 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1a670 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1a680 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1a690 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1a6a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a6b0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1a6c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a6d0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1a6e0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1a6f0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1a700 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1a710 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1a720 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1a730 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1a740 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1a750 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1a760 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1a770 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a780 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1a790 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1a7a0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1a7b0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1a7c0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1a7d0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1a7e0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1a7f0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1a800 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1a810 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1a820 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1a830 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1a840 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1a850 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1a860 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1a870 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1a880 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1a890 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1a8a0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1a8b0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1a8c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1a8d0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1a8e0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1a8f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1a900 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1a910 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1a920 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1a930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1a940 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1a950 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a960 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1a970 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1a980 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1a990 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1a9a0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1a9b0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1a9c0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1a9d0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1a9e0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1a9f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1aa00 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1aa10 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1aa20 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1aa30 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1aa40 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1aa50 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1aa60 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1aa70 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1aa80 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1aa90 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1aaa0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1aab0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1aac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1aad0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1aae0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1aaf0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1ab00 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1ab10 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1ab20 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1ab30 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1ab40 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1ab50 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1ab60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ab70 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1ab80 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1ab90 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1aba0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1abb0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1abc0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1abd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1abe0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1abf0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1ac00 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1ac10 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1ac20 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1ac30 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1ac40 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1ac50 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1ac60 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1ac70 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1ac80 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1ac90 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1aca0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1acb0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1acc0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1acd0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1ace0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1acf0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1ad00 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1ad10 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ad20 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ad30 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ad40 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1ad50 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ad60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1ad70 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1ad80 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1ad90 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1ada0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1adb0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1adc0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1add0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1ade0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1adf0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1ae00 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1ae10 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1ae20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1ae30 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1ae40 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1ae50 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1ae60 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1ae70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1ae80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1ae90 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1aea0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1aeb0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1aec0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1aed0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1aee0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1aef0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1af00 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1af10 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1af20 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1af30 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1af40 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1af50 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1af60 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1af70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1af80 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1af90 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1afa0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1afb0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1afc0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1afd0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1afe0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1aff0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1b000 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1b010 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1b020 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1b030 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1b040 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1b050 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1b060 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1b070 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1b080 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1b090 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1b0a0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1b0b0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1b0c0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1b0d0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1b0e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1b0f0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1b100 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1b110 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1b120 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1b130 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1b140 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1b150 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1b160 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1b170 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1b180 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1b190 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1b1a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1b1b0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1b1c0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1b1d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1b1e0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1b1f0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1b200 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1b210 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
1b220 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1b230 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1b240 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1b250 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1b260 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1b270 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1b280 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1b290 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1b2a0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1b2b0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1b2c0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1b2d0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1b2e0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1b2f0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1b300 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1b310 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1b320 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1b330 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1b340 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1b350 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1b360 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1b370 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1b380 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1b390 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1b3a0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1b3b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b3c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1b3d0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1b3e0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1b3f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b400 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1b410 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1b420 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1b430 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1b440 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b450 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1b460 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1b470 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1b480 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1b490 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1b4a0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1b4b0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1b4c0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1b4d0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1b4e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b4f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1b500 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1b510 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1b520 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1b530 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1b540 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1b550 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1b560 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1b570 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1b580 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1b590 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1b5a0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1b5b0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1b5c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b5d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1b5e0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1b5f0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1b600 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1b610 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1b620 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1b630 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1b640 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b650 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1b660 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1b670 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1b680 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1b690 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b6a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1b6b0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1b6c0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1b6d0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1b6e0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1b6f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1b700 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1b710 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1b720 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1b730 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1b740 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1b750 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1b760 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1b770 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1b780 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1b790 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1b7a0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1b7b0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1b7c0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1b7d0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1b7e0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1b7f0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1b800 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1b810 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1b820 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1b830 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1b840 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1b850 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1b860 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b870 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1b880 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1b890 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1b8a0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1b8b0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1b8c0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1b8d0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1b8e0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1b8f0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1b900 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b910 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1b920 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1b930 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1b940 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1b950 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1b960 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1b970 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1b980 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1b990 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1b9a0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1b9b0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1b9c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1b9d0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1b9e0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1b9f0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1ba00 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1ba10 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1ba20 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1ba30 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1ba40 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1ba50 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1ba60 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1ba70 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1ba80 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1ba90 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1baa0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1bab0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1bac0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1bad0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1bae0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1baf0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1bb00 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1bb10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bb20 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1bb30 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1bb40 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1bb50 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1bb60 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1bb70 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1bb80 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1bb90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1bba0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1bbb0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1bbc0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1bbd0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1bbe0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1bbf0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1bc00 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1bc10 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1bc20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1bc30 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1bc40 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1bc50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bc60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1bc70 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1bc80 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1bc90 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1bca0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1bcb0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1bcc0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1bcd0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1bce0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1bcf0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1bd00 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1bd10 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1bd20 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1bd30 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1bd40 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1bd50 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bd60 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1bd70 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1bd80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1bd90 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1bda0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1bdb0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1bdc0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1bdd0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1bde0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bdf0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1be00 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1be10 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1be20 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1be30 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1be40 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1be50 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1be60 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1be70 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1be80 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1be90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1bea0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1beb0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1bec0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1bed0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1bee0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1bef0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1bf00 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1bf10 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1bf20 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1bf30 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1bf40 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1bf50 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1bf60 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1bf70 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1bf80 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1bf90 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1bfa0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1bfb0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1bfc0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1bfd0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1bfe0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1bff0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1c000 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1c010 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1c020 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1c030 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1c040 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c050 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1c060 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1c070 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1c080 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1c090 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1c0a0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1c0b0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1c0c0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1c0d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1c0e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c0f0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1c100 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1c110 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1c120 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1c130 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1c140 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c150 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1c160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c170 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c180 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1c190 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1c1a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1c1b0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1c1c0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1c1d0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1c1e0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1c1f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c200 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1c210 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1c220 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1c230 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1c240 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1c250 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1c260 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c270 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1c280 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c290 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c2a0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1c2b0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1c2c0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1c2d0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1c2e0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1c2f0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1c300 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1c310 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1c320 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1c330 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1c340 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1c350 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1c360 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1c370 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1c380 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1c390 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1c3a0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c3b0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1c3c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1c3d0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1c3e0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1c3f0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1c400 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1c410 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1c420 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1c430 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1c440 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1c450 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1c460 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1c470 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1c480 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1c490 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1c4a0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1c4b0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1c4c0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1c4d0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1c4e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c4f0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1c500 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1c510 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1c520 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1c530 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1c540 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1c550 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1c560 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1c570 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1c580 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1c590 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c5a0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1c5b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c5c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1c5d0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1c5e0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1c5f0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1c600 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1c610 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1c620 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1c630 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1c640 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1c650 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1c660 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1c670 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1c680 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1c690 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1c6a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1c6b0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1c6c0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1c6d0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1c6e0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1c6f0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1c700 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1c710 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1c720 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1c730 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1c740 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1c750 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1c760 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1c770 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1c780 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1c790 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c7a0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1c7b0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1c7c0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1c7d0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1c7e0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1c7f0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1c800 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1c810 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1c820 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1c830 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1c840 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1c850 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1c860 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1c870 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1c880 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1c890 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1c8a0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1c8b0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1c8c0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1c8d0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1c8e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c8f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1c900 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1c910 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1c920 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1c930 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1c940 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1c950 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1c960 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1c970 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1c980 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1c990 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1c9a0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1c9b0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1c9c0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1c9d0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1c9e0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1c9f0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1ca00 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1ca10 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1ca20 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1ca30 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1ca40 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1ca50 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1ca60 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1ca70 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1ca80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1ca90 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1caa0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1cab0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1cac0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1cad0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1cae0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1caf0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1cb00 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1cb10 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1cb20 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1cb30 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1cb40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1cb50 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1cb60 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1cb70 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1cb80 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1cb90 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1cba0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1cbb0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1cbc0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1cbd0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1cbe0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1cbf0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1cc00 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1cc10 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1cc20 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1cc30 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1cc40 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1cc50 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1cc60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cc70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1cc80 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1cc90 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1cca0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1ccb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1ccc0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1ccd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1cce0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1ccf0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1cd00 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1cd10 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1cd20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1cd30 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1cd40 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1cd50 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1cd60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd70 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cd80 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1cd90 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1cda0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1cdb0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1cdc0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1cdd0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1cde0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cdf0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1ce00 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1ce10 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1ce20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1ce30 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1ce40 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1ce50 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1ce60 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1ce70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1ce80 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1ce90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1cea0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1ceb0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1cec0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1ced0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1cee0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1cef0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1cf00 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1cf10 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1cf20 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1cf30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cf40 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1cf50 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1cf60 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1cf70 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1cf80 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1cf90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1cfa0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1cfb0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cfc0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1cfd0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1cfe0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1cff0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1d000 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1d010 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1d020 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1d030 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1d040 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1d050 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1d060 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1d070 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d080 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1d090 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1d0a0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1d0b0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1d0c0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1d0d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1d0e0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1d0f0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1d100 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1d110 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d120 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1d130 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1d140 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1d150 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d160 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1d170 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1d180 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1d190 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1d1a0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1d1b0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1d1c0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1d1d0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1d1e0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1d1f0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1d200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1d210 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1d220 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1d230 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1d240 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1d250 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1d260 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1d270 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1d280 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1d290 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1d2a0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1d2b0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1d2c0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1d2d0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1d2e0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1d2f0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1d300 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1d310 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1d320 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1d330 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1d340 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1d350 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1d360 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1d370 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1d380 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1d390 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1d3a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1d3b0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1d3c0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1d3d0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1d3e0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1d3f0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1d400 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1d410 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d420 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1d430 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1d440 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1d450 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1d460 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1d470 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1d480 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1d490 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1d4a0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1d4b0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1d4c0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1d4d0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1d4e0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1d4f0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d500 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1d510 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1d520 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1d530 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1d540 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1d550 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1d560 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1d570 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1d580 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1d590 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1d5a0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1d5b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1d5c0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1d5d0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1d5e0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1d5f0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1d600 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1d610 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1d620 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1d630 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1d640 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1d650 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1d660 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d670 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1d680 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1d690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1d6a0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1d6b0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1d6c0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1d6d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d6e0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1d6f0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1d700 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1d710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1d720 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1d730 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1d740 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1d750 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d760 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1d770 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1d780 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1d790 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1d7a0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1d7b0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1d7c0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1d7d0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1d7e0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1d7f0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1d800 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1d810 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1d820 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1d830 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1d840 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d850 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1d860 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1d870 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1d880 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1d890 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1d8a0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1d8b0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1d8c0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1d8d0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1d8e0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1d8f0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1d900 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1d910 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1d920 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1d930 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1d940 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1d950 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d960 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1d970 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1d980 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1d990 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1d9a0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1d9b0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1d9c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1d9d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1d9e0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1d9f0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1da00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1da10 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1da20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1da30 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1da40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1da50 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1da60 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1da70 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1da80 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1da90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1daa0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1dab0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1dac0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1dad0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1dae0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1daf0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1db00 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1db10 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1db20 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1db30 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1db40 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1db50 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1db60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1db70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1db80 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1db90 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1dba0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1dbb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1dbc0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1dbd0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1dbe0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1dbf0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1dc00 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1dc10 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1dc20 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1dc30 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1dc40 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1dc50 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1dc60 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1dc70 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1dc80 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1dc90 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1dca0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1dcb0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1dcc0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1dcd0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1dce0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1dcf0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1dd00 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1dd10 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1dd20 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1dd30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1dd40 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1dd50 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1dd60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1dd70 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1dd80 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1dd90 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1dda0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1ddb0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1ddc0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1ddd0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1dde0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1ddf0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1de00 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1de10 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1de20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1de30 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1de40 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1de50 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1de60 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1de70 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1de80 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1de90 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1dea0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1deb0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1dec0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1ded0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1dee0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1def0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1df00 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1df10 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1df20 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1df30 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1df40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1df50 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1df60 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1df70 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1df80 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1df90 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1dfa0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1dfb0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1dfc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1dfd0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1dfe0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1dff0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1e000 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1e010 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1e020 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1e030 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1e040 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1e050 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1e060 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1e070 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1e080 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1e090 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1e0a0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1e0b0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1e0c0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1e0d0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1e0e0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1e0f0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1e100 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1e110 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1e120 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1e130 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1e140 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1e150 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1e160 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1e170 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1e180 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1e190 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1e1a0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1e1b0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1e1c0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1e1d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1e1e0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1e1f0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1e200 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1e210 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1e220 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1e230 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1e240 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1e250 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1e260 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1e270 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1e280 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1e290 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1e2a0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1e2b0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1e2c0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1e2d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1e2e0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1e2f0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1e300 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1e310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1e320 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1e330 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1e340 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e350 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1e360 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1e370 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1e380 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1e390 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1e3a0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1e3b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1e3c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1e3d0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1e3e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e3f0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1e400 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1e410 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1e420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e430 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1e440 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e450 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1e460 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1e470 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1e480 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1e490 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1e4a0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1e4b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1e4c0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1e4d0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1e4e0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1e4f0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1e500 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1e510 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1e520 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1e530 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1e540 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1e550 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1e560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1e570 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1e580 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1e590 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e5a0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1e5b0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1e5c0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1e5d0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1e5e0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1e5f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1e600 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1e610 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1e620 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e630 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1e640 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1e650 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1e660 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1e670 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1e680 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1e690 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1e6a0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1e6b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1e6c0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1e6d0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1e6e0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1e6f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1e700 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1e710 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1e720 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1e730 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1e740 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1e750 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1e760 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1e770 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1e780 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1e790 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1e7a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e7b0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1e7c0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1e7d0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1e7e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e7f0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1e800 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e810 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e820 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e830 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1e840 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1e850 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1e860 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1e870 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1e880 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1e890 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1e8a0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1e8b0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1e8c0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1e8d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1e8e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1e8f0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1e900 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1e910 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1e920 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1e930 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1e940 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1e950 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
1e960 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
1e970 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
1e980 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e990 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e9a0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e9b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e9c0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e9d0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e9e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e9f0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1ea00 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1ea10 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1ea20 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1ea30 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1ea40 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1ea50 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1ea60 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1ea70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1ea80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ea90 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1eaa0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1eab0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1eac0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1ead0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1eae0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1eaf0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1eb00 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1eb10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1eb20 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1eb30 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1eb40 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1eb50 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1eb60 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1eb70 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1eb80 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1eb90 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1eba0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ebb0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1ebc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1ebd0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1ebe0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1ebf0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1ec00 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1ec10 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1ec20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1ec30 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1ec40 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1ec50 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1ec60 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1ec70 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1ec80 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1ec90 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1eca0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1ecb0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1ecc0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1ecd0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1ece0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ecf0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1ed00 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1ed10 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1ed20 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1ed30 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1ed40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1ed50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ed60 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1ed70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1ed80 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ed90 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1eda0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1edb0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1edc0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1edd0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1ede0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1edf0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ee00 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ee10 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ee20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ee30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1ee40 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1ee50 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1ee60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ee70 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1ee80 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1ee90 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1eea0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1eeb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1eec0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1eed0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1eee0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1eef0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ef00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ef10 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1ef20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1ef30 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ef40 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ef50 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ef60 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1ef70 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1ef80 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ef90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1efa0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1efb0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1efc0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1efd0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1efe0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1eff0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f000 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1f010 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1f020 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f030 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f040 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f050 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1f060 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1f070 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1f080 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f090 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1f0a0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1f0b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1f0c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f0d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f0e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1f0f0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1f100 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f110 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f120 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f130 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1f140 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1f150 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f160 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f170 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f180 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1f190 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1f1a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f1b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f1c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f1d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1f1e0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1f1f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f200 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f220 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1f230 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1f240 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f250 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f270 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1f280 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1f290 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f2a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f2b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f2c0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1f2d0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1f2e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f2f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f310 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1f320 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1f330 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1f340 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f360 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1f370 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1f380 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f390 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f3a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1f3b0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1f3c0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1f3d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f3e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1f400 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1f410 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1f420 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1f430 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1f440 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1f450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f460 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1f470 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f480 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f490 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1f4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f4b0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1f4c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f4d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f4e0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1f4f0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1f500 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1f510 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f530 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1f540 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1f550 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f560 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f580 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1f590 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1f5a0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1f5b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f5c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f5d0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1f5e0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1f5f0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f620 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1f630 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1f640 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f650 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f670 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1f680 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1f690 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f6a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f6b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f6c0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1f6d0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1f6e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f6f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f710 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1f720 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1f730 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1f740 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1f750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f760 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1f770 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1f780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f790 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f7b0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1f7c0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1f7d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1f7e0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1f7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f800 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1f810 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1f820 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1f830 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1f840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1f850 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1f860 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1f870 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
1f880 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
1f890 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
1f8a0 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
1f8b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f8c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
1f8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f8e0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f8f0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f900 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f910 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f920 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f930 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f940 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f950 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f960 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f970 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f980 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f990 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f9a0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f9b0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f9c0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f9d0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f9e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f9f0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1fa00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1fa10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1fa20 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1fa30 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1fa40 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1fa50 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1fa60 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1fa70 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1fa80 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1fa90 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1faa0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1fab0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1fac0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1fad0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1fae0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1faf0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1fb00 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1fb10 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1fb20 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1fb30 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1fb40 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1fb50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1fb60 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1fb70 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1fb80 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1fb90 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1fba0 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1fbb0 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1fbc0 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1fbd0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1fbe0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1fbf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1fc00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1fc10 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1fc20 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1fc30 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1fc40 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1fc50 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1fc60 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fc70 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1fc80 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1fc90 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1fca0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1fcb0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1fcc0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1fcd0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1fce0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1fcf0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1fd00 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1fd10 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1fd20 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1fd30 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1fd40 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1fd50 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1fd60 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1fd70 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1fd80 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fd90 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fda0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fdb0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fdc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fdd0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fde0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fdf0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fe00 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fe10 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fe20 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1fe30 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fe40 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fe50 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fe60 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fe70 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fe80 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1fe90 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1fea0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1feb0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1fec0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1fed0 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1fee0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1fef0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1ff00 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1ff10 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1ff20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1ff30 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1ff40 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1ff50 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1ff60 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1ff70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ff80 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1ff90 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1ffa0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1ffb0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1ffc0 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1ffd0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1ffe0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1fff0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
20000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
20010 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
20020 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
20030 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
20040 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
20050 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
20060 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
20070 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
20080 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
20090 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
200a0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
200b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
200c0 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
200d0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
200e0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
200f0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
20100 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
20110 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
20120 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
20130 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
20140 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
20150 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
20160 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
20170 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
20180 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
20190 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
201a0 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
201b0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
201c0 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
201d0 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
201e0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
201f0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
20200 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
20210 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
20220 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
20230 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
20240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
20250 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
20260 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
20270 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
20280 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
20290 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
202a0 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
202b0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
202c0 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
202d0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
202e0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
202f0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
20300 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
20310 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
20320 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
20330 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
20340 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
20350 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
20360 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
20370 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
20380 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
20390 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
203a0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
203b0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
203c0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
203d0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
203e0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
203f0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20400 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
20410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20420 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
20430 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
20440 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
20450 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
20460 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
20470 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20480 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
20490 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
204a0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
204b0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
204c0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
204d0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
204e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
204f0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
20500 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
20510 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
20520 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20530 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
20540 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
20550 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
20560 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
20570 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
20580 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
20590 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
205a0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
205b0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
205c0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
205d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
205e0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
205f0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20600 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20610 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
20620 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
20630 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
20640 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
20650 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
20660 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20670 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
20680 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
20690 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
206a0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
206b0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
206c0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
206d0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
206e0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
206f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
20700 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
20710 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
20720 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
20730 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
20740 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
20750 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
20760 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
20770 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20780 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
20790 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
207a0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
207b0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
207c0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
207d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
207e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
207f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
20800 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
20810 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
20820 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
20830 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
20840 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
20850 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
20860 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
20870 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
20880 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
20890 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
208a0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
208b0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
208c0 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
208d0 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
208e0 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
208f0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
20900 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
20910 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
20920 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
20930 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
20940 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
20950 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20960 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
20970 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
20980 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
20990 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
209a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
209b0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
209c0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
209d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
209e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
209f0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20a00 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
20a10 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
20a20 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
20a30 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
20a40 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
20a50 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
20a60 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
20a70 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
20a80 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
20a90 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
20aa0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
20ab0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
20ac0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
20ad0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
20ae0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
20af0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
20b00 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
20b10 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
20b20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
20b30 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
20b40 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
20b50 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
20b60 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
20b70 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
20b80 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
20b90 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
20ba0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
20bb0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20bc0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20bd0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
20be0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20bf0 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
20c00 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
20c10 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
20c20 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20c30 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
20c40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20c50 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20c60 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
20c70 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
20c80 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
20c90 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
20ca0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20cb0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
20cc0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20cd0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20ce0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20cf0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20d00 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
20d10 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
20d20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
20d30 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
20d40 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
20d50 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
20d60 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20d70 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
20d80 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
20d90 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
20da0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
20db0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
20dc0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20dd0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20de0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20df0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
20e00 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
20e10 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20e20 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20e30 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
20e40 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
20e50 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
20e60 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
20e70 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
20e80 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
20e90 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
20ea0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
20eb0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
20ec0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
20ed0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
20ee0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
20ef0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20f00 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
20f10 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
20f20 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
20f30 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
20f40 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
20f50 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
20f60 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
20f70 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
20f80 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
20f90 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
20fa0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
20fb0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
20fc0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
20fd0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
20fe0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20ff0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
21000 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
21010 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
21020 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
21030 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
21040 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
21050 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
21060 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21070 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
21080 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
21090 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
210a0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
210b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
210c0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
210d0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
210e0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
210f0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
21100 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
21110 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
21120 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
21130 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21140 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
21150 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21160 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
21170 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21180 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
21190 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
211a0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
211b0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
211c0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
211d0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
211e0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
211f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
21200 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
21210 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
21220 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21230 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
21240 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
21250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21260 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
21270 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
21280 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
21290 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
212a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
212b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
212c0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
212d0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
212e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
212f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
21300 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
21310 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21320 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
21330 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
21340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
21350 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
21360 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
21370 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
21380 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
21390 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
213a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
213b0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
213c0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
213d0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
213e0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
213f0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
21400 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
21410 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
21420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
21430 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
21440 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
21450 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
21460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21470 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
21480 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21490 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
214a0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
214b0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
214c0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
214d0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
214e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
214f0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
21500 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
21510 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
21520 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
21530 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
21540 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
21550 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
21560 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
21570 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
21580 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
21590 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
215a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
215b0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
215c0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
215d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
215e0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
215f0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
21600 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
21610 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
21620 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
21630 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
21640 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
21650 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21660 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
21670 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
21680 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
21690 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
216a0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
216b0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
216c0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
216d0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
216e0 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
216f0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21700 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
21710 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
21720 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
21730 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
21740 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
21750 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
21760 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
21770 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21780 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
21790 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
217a0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
217b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
217c0 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
217d0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
217e0 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
217f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
21800 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
21810 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
21820 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
21830 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
21840 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
21850 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
21860 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
21870 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
21880 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
21890 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
218a0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
218b0 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
218c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
218d0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
218e0 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
218f0 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
21900 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
21910 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
21920 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
21930 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21940 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
21950 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
21960 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
21970 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
21980 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
21990 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
219a0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
219b0 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
219c0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
219d0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
219e0 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
219f0 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
21a00 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
21a10 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
21a20 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
21a30 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
21a40 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
21a50 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
21a60 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
21a70 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
21a80 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
21a90 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
21aa0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
21ab0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
21ac0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
21ad0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
21ae0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
21af0 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
21b00 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
21b10 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
21b20 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
21b30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21b40 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
21b50 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
21b60 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
21b70 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
21b80 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
21b90 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
21ba0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
21bb0 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
21bc0 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
21bd0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
21be0 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
21bf0 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
21c00 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
21c10 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
21c20 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
21c30 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
21c40 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
21c50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
21c60 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21c70 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
21c80 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21c90 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
21ca0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
21cb0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
21cc0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
21cd0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
21ce0 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
21cf0 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
21d00 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
21d10 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
21d20 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
21d30 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
21d40 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
21d50 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
21d60 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
21d70 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
21d80 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
21d90 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
21da0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
21db0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
21dc0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
21dd0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
21de0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21df0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
21e00 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
21e10 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
21e20 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
21e30 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
21e40 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
21e50 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
21e60 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
21e70 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
21e80 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
21e90 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
21ea0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
21eb0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
21ec0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
21ed0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
21ee0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
21ef0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
21f00 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
21f10 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
21f20 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
21f30 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
21f40 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
21f50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21f60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21f70 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
21f80 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
21f90 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
21fa0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
21fb0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
21fc0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
21fd0 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
21fe0 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
21ff0 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
22000 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
22010 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
22020 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22030 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22040 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22050 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22060 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
22070 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
22080 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
22090 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
220a0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
220b0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
220c0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
220d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
220e0 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
220f0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
22100 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
22110 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
22120 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22130 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
22140 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
22150 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
22160 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
22170 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
22180 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
22190 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
221a0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
221b0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
221c0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
221d0 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
221e0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
221f0 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
22200 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
22210 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
22220 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
22230 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
22240 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
22250 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
22260 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
22270 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
22280 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
22290 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
222a0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
222b0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
222c0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
222d0 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
222e0 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
222f0 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
22300 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
22310 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
22320 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
22330 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22340 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22350 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
22360 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
22370 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22380 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22390 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
223a0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
223b0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
223c0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
223d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
223e0 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
223f0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22400 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
22410 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
22420 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
22430 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22440 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
22450 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
22460 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
22470 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
22480 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
22490 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
224a0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
224b0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
224c0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
224d0 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
224e0 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
224f0 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
22500 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
22510 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
22520 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
22530 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
22540 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
22550 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22560 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
22570 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22580 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
22590 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
225a0 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
225b0 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
225c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
225d0 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
225e0 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
225f0 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
22600 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
22610 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
22620 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
22630 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
22640 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
22650 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
22660 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
22670 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
22680 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
22690 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
226a0 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
226b0 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
226c0 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
226d0 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
226e0 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
226f0 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
22700 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
22710 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
22720 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
22730 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
22740 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
22750 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
22760 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
22770 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
22780 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
22790 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
227a0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
227b0 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
227c0 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
227d0 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
227e0 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
227f0 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
22800 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
22810 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
22820 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
22830 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
22840 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
22850 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
22860 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
22870 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
22880 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
22890 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
228a0 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
228b0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
228c0 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
228d0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
228e0 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
228f0 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
22900 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
22910 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
22920 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22930 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
22940 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
22950 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
22960 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
22970 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
22980 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
22990 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
229a0 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
229b0 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
229c0 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
229d0 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
229e0 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
229f0 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
22a00 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
22a10 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
22a20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
22a30 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
22a40 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
22a50 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
22a60 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
22a70 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
22a80 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
22a90 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22aa0 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
22ab0 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
22ac0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22ad0 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
22ae0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
22af0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
22b00 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
22b10 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
22b20 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
22b30 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
22b40 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
22b50 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22b60 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
22b70 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
22b80 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
22b90 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
22ba0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
22bb0 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
22bc0 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
22bd0 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
22be0 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
22bf0 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
22c00 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
22c10 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22c20 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
22c30 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
22c40 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
22c50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22c60 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
22c70 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
22c80 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
22c90 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
22ca0 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
22cb0 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
22cc0 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
22cd0 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
22ce0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
22cf0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22d00 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
22d10 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
22d20 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
22d30 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
22d40 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
22d50 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
22d60 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
22d70 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
22d80 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
22d90 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
22da0 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
22db0 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
22dc0 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
22dd0 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
22de0 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
22df0 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
22e00 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
22e10 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
22e20 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
22e30 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
22e40 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
22e50 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
22e60 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
22e70 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
22e80 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
22e90 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
22ea0 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
22eb0 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
22ec0 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
22ed0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
22ee0 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
22ef0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22f00 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
22f10 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
22f20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22f30 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
22f40 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
22f50 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
22f60 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
22f70 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
22f80 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
22f90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
22fa0 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
22fb0 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
22fc0 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
22fd0 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
22fe0 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
22ff0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
23000 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
23010 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
23020 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
23030 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
23040 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
23050 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
23060 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
23070 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
23080 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
23090 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
230a0 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
230b0 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
230c0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
230d0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
230e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
230f0 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
23100 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
23110 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
23120 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
23130 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
23140 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
23150 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
23160 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
23170 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
23180 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
23190 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
231a0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
231b0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
231c0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
231d0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
231e0 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
231f0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
23200 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
23210 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
23220 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
23230 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
23240 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
23250 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
23260 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
23270 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
23280 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
23290 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
232a0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
232b0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
232c0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
232d0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
232e0 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
232f0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
23300 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
23310 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
23320 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
23330 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
23340 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
23350 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
23360 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
23370 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
23380 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
23390 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
233a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
233b0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
233c0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
233d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
233e0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
233f0 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
23400 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
23410 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
23420 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
23430 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
23440 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
23450 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
23460 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
23470 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
23480 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
23490 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
234a0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
234b0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
234c0 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
234d0 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
234e0 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
234f0 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
23500 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
23510 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
23520 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23530 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
23540 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
23550 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
23560 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
23570 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
23580 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
23590 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
235a0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
235b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
235c0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
235d0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
235e0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
235f0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
23600 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
23610 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23620 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23630 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
23640 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
23650 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
23660 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
23670 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
23680 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
23690 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
236a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
236b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
236c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
236d0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
236e0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
236f0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
23700 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
23710 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
23720 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23730 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23740 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
23750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23760 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
23770 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
23780 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
23790 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
237a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
237b0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
237c0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
237d0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
237e0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
237f0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
23800 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
23810 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
23820 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
23830 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
23840 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
23850 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
23860 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
23870 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
23880 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
23890 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
238a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
238b0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
238c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
238d0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
238e0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
238f0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
23900 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
23910 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
23920 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
23930 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
23940 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
23950 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23960 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
23970 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
23980 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
23990 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
239a0 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
239b0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
239c0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
239d0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
239e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
239f0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
23a00 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
23a10 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
23a20 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
23a30 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
23a40 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
23a50 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
23a60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23a70 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
23a80 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
23a90 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23aa0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
23ab0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
23ac0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
23ad0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
23ae0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
23af0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
23b00 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
23b10 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
23b20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
23b30 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
23b40 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
23b50 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
23b60 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
23b70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23b80 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23b90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
23ba0 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
23bb0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
23bc0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
23bd0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
23be0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
23bf0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
23c00 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23c10 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
23c20 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
23c30 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
23c40 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23c50 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23c60 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
23c70 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
23c80 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
23c90 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
23ca0 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
23cb0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
23cc0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
23cd0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
23ce0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
23cf0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
23d00 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
23d10 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
23d20 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
23d30 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
23d40 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
23d50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
23d60 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23d70 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
23d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23d90 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
23da0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
23db0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
23dc0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
23dd0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
23de0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
23df0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
23e00 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
23e10 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
23e20 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
23e30 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
23e40 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
23e50 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
23e60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
23e70 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
23e80 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
23e90 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23ea0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23eb0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
23ec0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23ed0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
23ee0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
23ef0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
23f00 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
23f10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
23f20 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
23f30 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
23f40 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
23f50 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
23f60 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
23f70 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
23f80 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
23f90 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
23fa0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
23fb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23fc0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23fd0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
23fe0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
23ff0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
24000 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
24010 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
24020 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
24030 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
24040 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
24050 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
24060 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
24070 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
24080 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
24090 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
240a0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
240b0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
240c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
240d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
240e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
240f0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
24100 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
24110 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
24120 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
24130 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
24140 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
24150 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
24160 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
24170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
24180 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
24190 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
241a0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
241b0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
241c0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
241d0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
241e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
241f0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
24200 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
24210 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
24220 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
24230 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
24240 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
24250 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
24260 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
24270 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
24280 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
24290 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
242a0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
242b0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
242c0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
242d0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
242e0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
242f0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
24300 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
24310 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
24320 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
24330 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
24340 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
24350 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
24360 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
24370 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
24380 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
24390 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
243a0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
243b0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
243c0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
243d0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
243e0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
243f0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
24400 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
24410 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
24420 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
24430 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
24440 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
24450 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
24460 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24470 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
24480 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
24490 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
244a0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
244b0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
244c0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
244d0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
244e0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
244f0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
24500 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
24510 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
24520 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
24530 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
24540 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24550 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
24560 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
24570 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
24580 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
24590 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
245a0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
245b0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
245c0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
245d0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
245e0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
245f0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
24600 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
24610 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
24620 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
24630 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
24640 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
24650 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
24660 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
24670 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
24680 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
24690 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
246a0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
246b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
246c0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
246d0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
246e0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
246f0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
24700 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
24710 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
24720 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
24730 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
24740 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
24750 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
24760 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
24770 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
24780 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
24790 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
247a0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
247b0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
247c0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
247d0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
247e0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
247f0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
24800 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
24810 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
24820 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
24830 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
24840 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
24850 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
24860 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
24870 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
24880 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
24890 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
248a0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
248b0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
248c0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
248d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
248e0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
248f0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
24900 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
24910 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
24920 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
24930 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
24940 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
24950 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
24960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
24970 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
24980 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
24990 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
249a0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
249b0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
249c0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
249d0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
249e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
249f0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
24a00 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
24a10 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
24a20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
24a30 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
24a40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
24a50 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
24a60 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
24a70 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
24a80 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
24a90 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
24aa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24ab0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
24ac0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
24ad0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
24ae0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
24af0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
24b00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
24b10 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
24b20 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
24b30 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
24b40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
24b50 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
24b60 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
24b70 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
24b80 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
24b90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
24ba0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
24bb0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
24bc0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
24bd0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
24be0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
24bf0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
24c00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
24c10 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
24c20 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
24c30 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
24c40 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
24c50 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
24c60 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
24c70 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
24c80 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
24c90 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
24ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24cb0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
24cc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
24cd0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
24ce0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
24cf0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
24d00 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
24d10 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
24d20 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
24d30 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
24d40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
24d50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
24d60 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
24d70 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
24d80 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
24d90 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
24da0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
24db0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
24dc0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
24dd0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
24de0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
24df0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
24e00 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
24e10 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
24e20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
24e30 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
24e40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
24e50 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
24e60 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
24e70 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
24e80 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
24e90 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
24ea0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
24eb0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
24ec0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
24ed0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
24ee0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
24ef0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
24f00 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
24f10 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
24f20 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
24f30 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
24f40 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
24f50 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
24f60 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
24f70 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
24f80 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
24f90 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
24fa0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
24fb0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
24fc0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
24fd0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
24fe0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
24ff0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
25000 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
25010 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
25020 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
25030 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
25040 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25050 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
25060 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
25070 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
25080 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
25090 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
250a0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
250b0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
250c0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
250d0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
250e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
250f0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
25100 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
25110 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
25120 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
25130 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
25140 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
25150 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
25160 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
25170 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
25180 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
25190 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
251a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
251b0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
251c0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
251d0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
251e0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
251f0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
25200 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
25210 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
25220 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
25230 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
25240 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
25250 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
25260 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
25270 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
25280 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
25290 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
252a0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
252b0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
252c0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
252d0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
252e0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
252f0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
25300 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
25310 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
25320 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
25330 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
25340 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
25350 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
25360 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
25370 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
25380 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
25390 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
253a0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
253b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
253c0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
253d0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
253e0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
253f0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
25400 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
25410 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
25420 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
25430 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
25440 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
25450 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
25460 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
25470 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
25480 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
25490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
254a0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
254b0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
254c0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
254d0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
254e0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
254f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
25500 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
25510 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
25520 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
25530 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
25540 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
25550 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
25560 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
25570 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
25580 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
25590 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
255a0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
255b0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
255c0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
255d0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
255e0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
255f0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
25600 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
25610 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25620 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
25630 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25640 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
25650 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
25660 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
25670 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
25680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25690 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
256a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
256b0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
256c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
256d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
256e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
256f0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
25700 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25710 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
25720 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25730 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
25740 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25750 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
25760 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
25770 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
25780 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
25790 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
257a0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
257b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
257c0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
257d0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
257e0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
257f0 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
25800 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25810 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
25820 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25830 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
25840 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25850 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
25860 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
25870 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
25880 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
258a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
258b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
258c0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
258d0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
258e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
258f0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
25900 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
25910 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
25920 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25930 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
25940 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25950 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
25960 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25970 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
25980 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
25990 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
259a0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
259b0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
259c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
259d0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
259e0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
259f0 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
25a00 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
25a10 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
25a20 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
25a30 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
25a40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25a50 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25a60 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25a70 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
25a80 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
25a90 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25aa0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
25ab0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
25ac0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25ad0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
25ae0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
25af0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25b00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25b10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25b20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
25b30 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
25b40 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
25b50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
25b60 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
25b70 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
25b80 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
25b90 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
25ba0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25bb0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
25bc0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
25bd0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
25be0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
25bf0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
25c00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25c10 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25c20 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
25c30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
25c40 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
25c50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25c60 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
25c70 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
25c80 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
25c90 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
25ca0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25cb0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
25cc0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25cd0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
25ce0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
25cf0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
25d00 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
25d10 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
25d20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25d30 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
25d40 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
25d50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
25d60 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
25d70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25d80 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
25d90 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
25da0 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
25db0 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
25dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
25dd0 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
25de0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
25df0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25e00 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
25e10 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
25e20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25e30 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
25e40 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
25e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25e60 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
25e70 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
25e80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25e90 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
25ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
25eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25ec0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
25ed0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
25ee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25ef0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
25f00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
25f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25f20 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
25f30 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
25f40 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
25f50 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
25f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25f70 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
25f80 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25f90 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
25fa0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
25fb0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25fc0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
25fd0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
25fe0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25ff0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
26000 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
26010 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
26020 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
26030 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
26040 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
26050 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
26060 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
26070 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
26080 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
26090 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
260a0 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
260b0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
260c0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
260d0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
260e0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
260f0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
26100 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
26110 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
26120 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26130 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
26140 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
26150 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
26160 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
26170 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
26180 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
26190 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
261a0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
261b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
261c0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
261d0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
261e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
261f0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
26200 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
26210 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
26220 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
26230 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
26240 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
26250 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
26260 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
26270 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
26280 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
26290 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
262a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
262b0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
262c0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
262d0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
262e0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
262f0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
26300 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
26310 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
26320 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26330 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
26340 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
26350 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
26360 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
26370 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
26380 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
26390 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
263a0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
263b0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
263c0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
263d0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
263e0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
263f0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
26400 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
26410 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
26420 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
26430 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
26440 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
26450 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
26460 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
26470 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
26480 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
26490 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
264a0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
264b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
264c0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
264d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
264e0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
264f0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
26500 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
26510 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
26520 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
26530 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
26540 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
26550 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
26560 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
26570 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
26580 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
26590 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
265a0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
265b0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
265c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
265d0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
265e0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
265f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
26600 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
26610 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
26620 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
26630 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
26640 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
26650 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
26660 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
26670 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
26680 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
26690 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
266a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
266b0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
266c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
266d0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
266e0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
266f0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
26700 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
26710 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
26720 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
26730 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
26740 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
26750 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
26760 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
26770 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
26780 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
26790 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
267a0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
267b0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
267c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
267d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
267e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
267f0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
26800 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
26810 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
26820 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
26830 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
26840 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
26850 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
26860 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
26870 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
26880 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
26890 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
268a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
268b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
268c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
268d0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
268e0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
268f0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
26900 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
26910 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
26920 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
26930 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
26940 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
26950 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
26960 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
26970 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
26980 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
26990 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
269a0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
269b0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
269c0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
269d0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
269e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
269f0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
26a00 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
26a10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
26a20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
26a30 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
26a40 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
26a50 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
26a60 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26a70 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
26a80 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
26a90 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
26aa0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
26ab0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
26ac0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
26ad0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26ae0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
26af0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
26b00 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
26b10 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
26b20 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
26b30 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
26b40 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
26b50 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
26b60 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
26b70 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
26b80 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
26b90 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
26ba0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
26bb0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
26bc0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
26bd0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
26be0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
26bf0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
26c00 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
26c10 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
26c20 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
26c30 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
26c40 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
26c50 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
26c60 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
26c70 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
26c80 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
26c90 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
26ca0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
26cb0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
26cc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26cd0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
26ce0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
26cf0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
26d00 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
26d10 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
26d20 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
26d30 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
26d40 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
26d50 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
26d60 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
26d70 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
26d80 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
26d90 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
26da0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
26db0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
26dc0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
26dd0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
26de0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
26df0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
26e00 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
26e10 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
26e20 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
26e30 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
26e40 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26e50 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
26e60 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
26e70 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
26e80 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
26e90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
26ea0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
26eb0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
26ec0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
26ed0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
26ee0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
26ef0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
26f00 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
26f10 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
26f20 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
26f30 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
26f40 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26f50 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
26f60 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
26f70 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
26f80 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
26f90 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
26fa0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
26fb0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
26fc0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
26fd0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
26fe0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
26ff0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
27000 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
27010 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
27020 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
27030 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
27040 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27050 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27060 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27070 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27080 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27090 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
270a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
270b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
270c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
270d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
270e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
270f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27100 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27110 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27120 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27130 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27140 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27150 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27160 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
27170 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27180 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
27190 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
271a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
271b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
271c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
271d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
271e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
271f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27200 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27210 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27220 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27230 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27240 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27250 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27260 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27270 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
27280 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27290 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
272a0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
272b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
272c0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
272d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
272e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
272f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27300 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
27310 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
27320 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
27330 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
27340 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27350 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27360 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27370 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27380 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27390 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
273a0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
273b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
273c0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
273d0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
273e0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
273f0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
27400 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27410 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
27420 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27430 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27440 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27450 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27460 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27470 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
27480 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
27490 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
274a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
274b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
274c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
274d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
274e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
274f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27500 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
27510 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
27520 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
27530 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
27540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27550 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
27560 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
27570 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
27580 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
27590 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
275a0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
275b0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
275c0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
275d0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
275e0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
275f0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
27600 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
27610 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
27620 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27630 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27640 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
27650 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27660 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
27670 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27690 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
276a0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
276b0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
276c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
276d0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
276e0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
276f0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
27700 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
27710 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
27720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27730 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
27740 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
27750 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27760 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27770 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
27780 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
27790 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
277a0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
277b0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
277c0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
277d0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
277e0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
277f0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
27800 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
27810 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
27820 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
27830 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
27840 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
27850 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
27860 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
27870 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
27880 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
27890 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
278a0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
278b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
278c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
278d0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
278e0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
278f0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
27900 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
27910 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
27920 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
27930 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
27940 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27950 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
27960 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
27970 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
27980 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
27990 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
279a0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
279b0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
279c0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
279d0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
279e0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
279f0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
27a00 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
27a10 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
27a20 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
27a30 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
27a40 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
27a50 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
27a60 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
27a70 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
27a80 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
27a90 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
27aa0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
27ab0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
27ac0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
27ad0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
27ae0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
27af0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
27b00 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
27b10 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
27b20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
27b30 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
27b40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
27b50 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
27b60 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
27b70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
27b80 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
27b90 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
27ba0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27bb0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27bc0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
27bd0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
27be0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
27bf0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27c10 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
27c20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27c30 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
27c40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27c50 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
27c60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27c70 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
27c80 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
27c90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27ca0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
27cb0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
27cc0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
27cd0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
27ce0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
27cf0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
27d00 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
27d10 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
27d20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
27d30 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
27d40 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
27d50 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
27d60 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
27d70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27d80 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
27d90 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
27da0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
27db0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
27dc0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27dd0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
27de0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27df0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
27e00 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
27e10 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
27e20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
27e30 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
27e40 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
27e50 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
27e60 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
27e70 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
27e80 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
27e90 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
27ea0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
27eb0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
27ec0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
27ed0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
27ee0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
27ef0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
27f00 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
27f10 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
27f20 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
27f30 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
27f40 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
27f50 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
27f60 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
27f70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
27f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27f90 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
27fa0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
27fb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
27fc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27fd0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
27fe0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27ff0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
28000 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
28010 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
28020 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
28030 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
28040 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
28050 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
28060 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28070 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
28080 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
28090 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
280a0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
280b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
280c0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
280d0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
280e0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
280f0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
28100 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
28110 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28120 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
28130 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
28140 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
28150 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
28160 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
28170 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28180 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
28190 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
281a0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
281b0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
281c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
281d0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
281e0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
281f0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
28200 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
28210 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
28220 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
28230 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
28240 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28250 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
28260 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
28270 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
28280 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
28290 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
282a0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
282b0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
282c0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
282d0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
282e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
282f0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
28300 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
28310 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28320 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28330 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
28340 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
28350 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
28360 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
28370 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
28380 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
28390 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
283a0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
283b0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
283c0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
283d0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
283e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
283f0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
28400 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
28410 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
28420 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
28430 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
28440 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28450 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28460 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28470 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
28480 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
28490 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
284a0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
284b0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
284c0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
284d0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
284e0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
284f0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
28500 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
28510 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28520 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28530 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28540 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
28550 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
28560 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
28570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28580 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
28590 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
285a0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
285b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
285c0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
285d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
285e0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
285f0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
28600 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28610 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
28620 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28630 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
28640 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
28650 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
28660 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28670 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
28680 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
28690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
286a0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
286b0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
286c0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
286d0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
286e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
286f0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
28700 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
28710 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
28720 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28730 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
28740 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
28750 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
28760 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
28770 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
28780 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
28790 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
287a0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
287b0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
287c0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
287d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
287e0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
287f0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
28800 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
28810 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
28820 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
28830 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28840 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28850 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
28860 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28870 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28880 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
28890 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
288a0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
288b0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
288c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
288d0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
288e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
288f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
28900 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
28910 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
28920 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
28930 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
28940 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
28950 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
28960 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
28970 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
28980 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
28990 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
289a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
289b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
289c0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
289d0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
289e0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
289f0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
28a00 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
28a10 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
28a20 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
28a30 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
28a40 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
28a50 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
28a60 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
28a70 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
28a80 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
28a90 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
28aa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28ab0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
28ac0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
28ad0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
28ae0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
28af0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
28b00 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
28b10 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
28b20 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
28b30 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
28b40 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
28b50 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
28b60 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
28b70 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
28b80 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
28b90 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
28ba0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
28bb0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
28bc0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
28bd0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
28be0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
28bf0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
28c00 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
28c10 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
28c20 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
28c30 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
28c40 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
28c50 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
28c60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28c70 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
28c80 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
28c90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
28ca0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28cb0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
28cc0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
28cd0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
28ce0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
28cf0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
28d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
28d10 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
28d20 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
28d30 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
28d40 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
28d50 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
28d60 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
28d70 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
28d80 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
28d90 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
28da0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
28db0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
28dc0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
28dd0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
28de0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
28df0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
28e00 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
28e10 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
28e20 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
28e30 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
28e40 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
28e50 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
28e60 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
28e70 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
28e80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28e90 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
28ea0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
28eb0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
28ec0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
28ed0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
28ee0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
28ef0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
28f00 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
28f10 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28f20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
28f30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
28f40 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
28f50 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
28f60 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
28f70 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
28f80 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
28f90 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
28fa0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
28fb0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
28fc0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
28fd0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
28fe0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
28ff0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
29000 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
29010 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
29020 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
29030 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
29040 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
29050 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
29060 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
29070 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
29080 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
29090 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
290a0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
290b0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
290c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
290d0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
290e0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
290f0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
29100 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
29110 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
29120 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
29130 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
29140 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
29150 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
29160 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29170 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
29180 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29190 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
291a0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
291b0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
291c0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
291d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
291e0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
291f0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
29200 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
29210 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
29220 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29230 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
29240 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
29250 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
29260 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
29270 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
29280 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
29290 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
292a0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
292b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
292c0 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
292d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
292e0 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
292f0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
29300 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
29310 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
29320 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
29330 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
29340 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
29350 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
29360 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
29370 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
29380 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
29390 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
293a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
293b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
293c0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
293d0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
293e0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
293f0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
29400 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
29410 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
29420 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
29430 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
29440 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
29450 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
29460 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
29470 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
29480 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
29490 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
294a0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
294b0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
294c0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
294d0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
294e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
294f0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
29500 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
29510 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
29520 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
29530 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
29540 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
29550 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
29560 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
29570 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
29580 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
29590 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
295a0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
295b0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
295c0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
295d0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
295e0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
295f0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
29600 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
29610 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
29620 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
29630 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
29640 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
29650 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
29660 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
29670 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
29680 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
29690 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
296a0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
296b0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
296c0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
296d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
296e0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
296f0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
29700 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
29710 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
29720 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
29730 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
29740 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
29750 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
29760 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
29770 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
29780 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
29790 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
297a0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
297b0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
297c0 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
297d0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
297e0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
297f0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
29800 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
29810 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
29820 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
29830 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
29840 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
29850 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
29860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29870 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29880 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
29890 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
298a0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
298b0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
298c0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
298d0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
298e0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
298f0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
29900 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
29910 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
29920 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
29930 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
29940 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
29950 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
29960 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
29970 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
29980 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
29990 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
299a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
299b0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
299c0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
299d0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
299e0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
299f0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
29a00 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
29a10 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
29a20 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
29a30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29a40 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
29a50 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
29a60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
29a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29a80 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
29a90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
29aa0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
29ab0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
29ac0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
29ad0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
29ae0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29af0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
29b00 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
29b10 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
29b20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
29b30 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
29b40 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
29b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29b60 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
29b70 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
29b80 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
29b90 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
29ba0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
29bb0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
29bc0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
29bd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
29be0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
29bf0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
29c00 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
29c10 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
29c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29c30 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
29c40 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
29c50 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
29c60 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
29c70 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
29c80 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
29c90 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
29ca0 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
29cb0 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
29cc0 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
29cd0 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
29ce0 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
29cf0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
29d00 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
29d10 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
29d20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
29d30 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
29d40 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
29d50 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
29d60 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
29d70 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
29d80 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
29d90 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
29da0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
29db0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29dd0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
29de0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29df0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
29e00 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
29e10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29e20 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
29e30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29e40 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
29e50 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
29e60 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
29e70 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
29e80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29e90 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
29ea0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29eb0 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
29ec0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
29ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
29ee0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
29ef0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
29f00 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
29f10 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
29f20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29f30 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
29f40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
29f50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29f60 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
29f70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
29f80 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
29f90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
29fa0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
29fb0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
29fc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
29fd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
29fe0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
29ff0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a000 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a010 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2a020 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a030 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2a040 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2a050 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a060 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2a070 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2a080 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2a090 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2a0a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a0b0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2a0c0 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2a0d0 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
2a0e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2a0f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a100 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2a110 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2a120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2a130 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2a140 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2a150 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a160 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2a170 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
2a180 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2a190 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2a1a0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2a1b0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2a1c0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2a1d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a1e0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2a1f0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2a200 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2a210 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2a220 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2a230 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2a240 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2a250 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2a260 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2a270 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2a280 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2a290 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2a2a0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2a2b0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2a2c0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2a2d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2a2e0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2a2f0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2a300 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2a310 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2a320 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2a330 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2a340 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2a350 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2a360 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2a370 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2a380 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2a390 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2a3a0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2a3b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2a3c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2a3d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2a3e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a3f0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2a400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a410 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a420 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2a430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a440 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2a450 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2a460 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2a470 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2a480 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
2a490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a4a0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2a4b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a4c0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2a4d0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2a4e0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2a4f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a500 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2a510 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2a520 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2a530 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2a540 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2a550 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2a560 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2a570 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2a580 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2a590 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2a5a0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2a5b0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2a5c0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2a5d0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2a5e0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2a5f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2a600 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2a610 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2a620 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2a630 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2a640 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2a650 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2a660 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2a670 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2a680 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2a690 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2a6a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2a6b0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2a6c0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2a6d0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2a6e0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2a6f0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2a700 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2a710 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2a720 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2a730 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2a740 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2a750 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2a760 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2a770 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2a780 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2a790 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2a7a0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2a7b0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2a7c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2a7d0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2a7e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a7f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a800 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a820 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a830 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2a840 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a850 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2a860 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2a870 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a880 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2a890 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2a8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a8b0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2a8c0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2a8d0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
2a8e0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2a8f0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2a900 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2a910 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2a920 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2a930 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2a940 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2a950 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2a960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2a970 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2a980 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2a990 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2a9a0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2a9b0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2a9c0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2a9d0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2a9e0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2a9f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2aa00 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2aa10 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2aa20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2aa30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2aa40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2aa50 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2aa60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2aa70 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2aa80 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2aa90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2aaa0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2aab0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2aac0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2aad0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2aae0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2aaf0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2ab00 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2ab10 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2ab20 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2ab30 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2ab40 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ab50 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
2ab60 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2ab70 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2ab80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ab90 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2aba0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2abb0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2abc0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2abd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2abe0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2abf0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2ac00 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2ac10 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2ac20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2ac30 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2ac40 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ac50 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2ac60 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2ac70 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2ac80 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2ac90 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2aca0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2acb0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2acc0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2acd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2ace0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2acf0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2ad00 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2ad10 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2ad20 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2ad30 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2ad40 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2ad50 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ad60 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2ad70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ad80 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2ad90 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ada0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2adb0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2adc0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2add0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ade0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2adf0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2ae00 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2ae10 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2ae20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2ae30 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ae40 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2ae50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2ae60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2ae70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ae80 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2ae90 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2aea0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2aeb0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2aec0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2aed0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2aee0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2aef0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2af00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2af10 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2af20 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2af30 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2af40 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2af50 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2af60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2af70 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2af80 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2af90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2afa0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2afb0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2afc0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2afd0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2afe0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2aff0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2b000 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2b010 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b020 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2b030 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2b040 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2b050 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2b060 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2b070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2b080 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2b090 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2b0a0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2b0b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2b0c0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2b0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2b0e0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2b0f0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2b100 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2b110 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2b120 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2b130 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2b140 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2b150 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2b160 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2b170 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2b180 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2b190 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2b1a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2b1b0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2b1c0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2b1d0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2b1e0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2b1f0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2b200 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2b210 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2b220 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2b230 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2b240 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2b250 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2b260 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2b270 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2b280 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2b290 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
2b2a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b2b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b2c0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
2b2d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b2e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2b2f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b300 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2b310 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2b320 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2b330 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
2b340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2b350 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2b360 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2b370 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2b380 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2b390 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2b3a0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2b3b0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2b3c0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2b3d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2b3e0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2b3f0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2b400 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2b410 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2b420 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2b430 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2b440 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2b450 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2b460 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2b470 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2b480 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2b490 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2b4a0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2b4b0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2b4c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2b4d0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2b4e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b4f0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2b500 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2b510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2b520 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2b530 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2b540 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2b550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b560 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2b570 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2b580 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2b590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b5a0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2b5b0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2b5c0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2b5d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2b5e0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2b5f0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2b600 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2b610 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2b620 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2b630 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2b640 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2b650 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2b660 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2b670 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2b680 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2b690 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2b6a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b6b0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2b6c0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2b6d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2b6e0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2b6f0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2b700 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2b710 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2b720 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2b730 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2b740 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2b750 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2b760 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2b770 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2b780 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2b790 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2b7a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2b7b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2b7c0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2b7d0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2b7e0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2b7f0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2b800 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2b810 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2b820 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2b830 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2b840 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2b850 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2b860 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2b870 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2b880 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2b890 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2b8a0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2b8b0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2b8c0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2b8d0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2b8e0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2b8f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2b900 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2b910 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2b920 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2b930 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2b940 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2b950 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2b960 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2b970 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2b980 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2b990 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2b9a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2b9b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2b9c0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2b9d0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2b9e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2b9f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2ba00 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2ba10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2ba20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2ba30 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2ba40 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2ba50 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2ba60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2ba70 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2ba80 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2ba90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2baa0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2bab0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2bac0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2bad0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2bae0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2baf0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2bb00 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2bb10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2bb20 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2bb30 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2bb40 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2bb50 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2bb60 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2bb70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bb80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2bb90 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2bba0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2bbb0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2bbc0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2bbd0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2bbe0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2bbf0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2bc00 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2bc10 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2bc20 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2bc30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bc40 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2bc50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2bc60 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2bc70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2bc80 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2bc90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2bca0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2bcb0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2bcc0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2bcd0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2bce0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2bcf0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2bd00 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2bd10 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2bd20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2bd30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bd40 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2bd50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2bd60 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2bd70 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2bd80 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2bd90 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2bda0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2bdb0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2bdc0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2bdd0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2bde0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2bdf0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2be00 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2be10 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2be20 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2be30 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2be40 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2be50 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2be60 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2be70 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2be80 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2be90 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2bea0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2beb0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2bec0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2bed0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2bee0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2bef0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2bf00 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2bf10 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2bf20 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2bf30 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2bf40 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2bf50 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2bf60 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2bf70 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2bf80 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2bf90 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2bfa0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2bfb0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2bfc0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2bfd0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2bfe0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2bff0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2c000 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2c010 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2c020 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2c030 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2c040 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2c050 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2c060 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2c070 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2c080 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2c090 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2c0a0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2c0b0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2c0c0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2c0d0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2c0e0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2c0f0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2c100 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2c110 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2c120 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2c130 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2c140 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2c150 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2c160 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2c170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2c180 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2c190 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c1a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c1b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2c1c0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2c1d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2c1e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2c1f0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2c200 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
2c210 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2c220 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2c230 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2c240 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2c250 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c260 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2c270 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2c280 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2c290 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2c2a0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2c2b0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2c2c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2c2d0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2c2e0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2c2f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2c300 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2c310 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2c320 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2c330 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2c340 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2c350 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2c360 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2c370 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2c380 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2c390 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2c3a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2c3b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c3c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2c3d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c3e0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2c3f0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2c400 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2c410 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2c420 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c430 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2c440 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2c450 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2c460 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2c470 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2c480 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2c490 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2c4a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2c4b0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2c4c0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2c4d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2c4e0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2c4f0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2c500 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2c510 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2c520 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2c530 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2c540 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2c550 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2c560 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2c570 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2c580 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2c590 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2c5a0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
2c5b0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
2c5c0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
2c5d0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
2c5e0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
2c5f0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
2c600 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
2c610 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
2c620 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
2c630 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
2c640 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c650 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
2c660 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
2c670 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
2c680 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2c690 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
2c6a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
2c6b0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
2c6c0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
2c6d0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
2c6e0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
2c6f0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2c700 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
2c710 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
2c720 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
2c730 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
2c740 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2c750 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
2c760 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2c770 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2c780 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
2c790 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
2c7a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2c7b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2c7c0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
2c7d0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
2c7e0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
2c7f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2c800 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2c810 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2c820 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2c830 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2c840 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2c850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2c860 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2c870 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2c880 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2c890 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2c8a0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2c8b0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2c8c0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2c8d0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2c8e0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2c8f0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2c900 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2c910 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2c920 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2c930 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2c940 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2c950 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2c960 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2c970 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2c980 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2c990 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2c9a0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2c9b0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2c9c0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2c9d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2c9e0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2c9f0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2ca00 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2ca10 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2ca20 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2ca30 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2ca40 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2ca50 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2ca60 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2ca70 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2ca80 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2ca90 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2caa0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2cab0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2cac0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2cad0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2cae0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2caf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cb00 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2cb10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cb20 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2cb30 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2cb40 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2cb50 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2cb60 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2cb70 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2cb80 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2cb90 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2cba0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2cbb0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2cbc0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2cbd0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2cbe0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2cbf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cc00 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2cc10 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2cc20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2cc30 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2cc40 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2cc50 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2cc60 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2cc70 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2cc80 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2cc90 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2cca0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2ccb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2ccc0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2ccd0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2cce0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2ccf0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2cd00 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2cd10 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2cd20 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2cd30 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2cd40 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2cd50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2cd60 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2cd70 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2cd80 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2cd90 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2cda0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2cdb0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2cdc0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2cdd0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2cde0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2cdf0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2ce00 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2ce10 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2ce20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ce30 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2ce40 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2ce50 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2ce60 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2ce70 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2ce80 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2ce90 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2cea0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2ceb0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2cec0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2ced0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2cee0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2cef0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2cf00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2cf10 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2cf20 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2cf30 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2cf40 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2cf50 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2cf60 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2cf70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2cf80 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2cf90 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2cfa0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2cfb0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2cfc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2cfd0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2cfe0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2cff0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2d000 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2d010 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2d020 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2d030 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2d040 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2d050 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2d060 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2d070 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2d080 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2d090 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2d0a0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2d0b0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2d0c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d0d0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2d0e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d0f0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2d100 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2d110 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2d120 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2d130 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2d140 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2d150 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2d160 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2d170 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2d180 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2d190 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2d1a0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2d1b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2d1c0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2d1d0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2d1e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2d1f0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2d200 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d210 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2d220 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d230 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2d240 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2d250 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2d270 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2d280 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2d290 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2d2a0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2d2b0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2d2c0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2d2d0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2d2e0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2d2f0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2d300 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
2d310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2d320 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2d330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2d340 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2d350 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2d360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d370 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d390 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2d3a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2d3b0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2d3c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2d3d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2d3e0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2d3f0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2d400 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2d410 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2d420 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2d430 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2d440 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2d450 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2d460 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2d470 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2d480 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2d490 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2d4a0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2d4b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2d4c0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2d4d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2d4e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2d4f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d500 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2d510 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d520 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2d530 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2d540 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2d550 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d560 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2d570 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2d580 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2d590 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2d5a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2d5b0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2d5c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2d5d0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2d5e0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2d5f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2d600 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2d610 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2d620 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2d630 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2d640 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2d650 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2d660 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2d670 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2d680 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2d690 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2d6a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2d6b0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2d6c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d6d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d6e0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2d6f0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2d700 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2d710 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2d720 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2d730 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2d740 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2d750 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2d760 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2d770 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2d780 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2d790 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2d7a0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2d7b0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2d7c0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2d7d0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2d7e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2d7f0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2d800 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2d810 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2d820 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2d830 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2d840 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2d850 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d860 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2d870 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2d880 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2d890 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2d8a0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2d8b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2d8c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2d8d0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2d8e0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2d8f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2d900 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2d910 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2d920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2d930 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2d940 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2d950 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2d960 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2d970 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2d980 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2d990 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2d9a0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2d9b0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2d9c0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2d9d0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2d9e0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2d9f0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2da00 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2da10 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2da20 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2da30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2da40 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2da50 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2da60 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2da70 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2da80 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2da90 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2daa0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2dab0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2dac0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2dad0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2dae0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2daf0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2db00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2db10 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2db20 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2db30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2db40 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2db50 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2db60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2db70 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2db80 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2db90 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2dba0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2dbb0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2dbc0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2dbd0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2dbe0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2dbf0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2dc00 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2dc10 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2dc20 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2dc30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2dc40 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2dc50 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2dc60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2dc70 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2dc80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2dc90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2dca0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2dcb0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2dcc0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2dcd0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2dce0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2dcf0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2dd00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2dd10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2dd20 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2dd30 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2dd40 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2dd50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2dd60 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2dd70 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2dd80 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2dd90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2dda0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ddb0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2ddc0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2ddd0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2dde0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ddf0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2de00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2de10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2de20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2de30 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2de40 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2de50 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2de60 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2de70 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2de80 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2de90 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2dea0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2deb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dec0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2ded0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2dee0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2def0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2df00 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2df10 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2df20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2df30 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2df40 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2df50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2df60 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2df70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2df80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2df90 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2dfa0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2dfb0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2dfc0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2dfd0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2dfe0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2dff0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2e000 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2e010 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2e020 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2e030 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2e040 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2e050 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2e060 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2e070 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2e080 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2e090 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2e0a0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2e0b0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2e0c0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2e0d0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2e0e0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2e0f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2e100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e110 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2e120 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2e130 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2e140 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2e150 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2e160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2e170 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2e180 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2e190 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2e1a0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2e1b0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2e1c0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2e1d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e1e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2e1f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e200 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2e210 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2e220 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e230 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2e240 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2e250 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e260 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2e270 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2e280 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2e290 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e2a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2e2b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2e2c0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2e2d0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e2e0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2e2f0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2e300 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2e310 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2e320 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2e330 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2e340 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e350 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2e360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e370 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2e380 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e390 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2e3a0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2e3b0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e3c0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2e3d0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2e3e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e3f0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2e400 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2e410 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e420 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2e430 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e440 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2e450 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2e460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e470 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2e480 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2e490 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2e4a0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2e4b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2e4c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e4d0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2e4e0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2e4f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e500 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2e510 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2e520 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2e530 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2e540 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2e550 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2e560 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e570 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2e580 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e590 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2e5a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e5b0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2e5c0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2e5d0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2e5e0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2e5f0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2e600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e610 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2e620 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2e630 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2e640 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2e650 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2e660 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2e670 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2e680 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2e690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2e6a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2e6b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2e6c0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2e6d0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2e6e0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2e6f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2e700 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2e710 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2e720 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2e730 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2e740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e750 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2e760 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2e770 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2e780 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2e790 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2e7a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2e7b0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2e7c0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2e7d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e7e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2e7f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2e800 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2e810 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2e820 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2e830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e840 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2e850 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e860 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2e870 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2e880 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2e890 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2e8a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2e8b0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2e8c0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2e8d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e8e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2e8f0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2e900 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2e910 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2e920 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2e930 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2e940 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2e950 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2e960 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2e970 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2e980 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2e990 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2e9a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2e9b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e9c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e9d0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2e9e0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2e9f0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2ea00 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2ea10 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2ea20 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2ea30 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2ea40 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2ea50 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2ea60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2ea70 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2ea80 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2ea90 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2eaa0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2eab0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2eac0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2ead0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2eae0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2eaf0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2eb00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2eb10 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2eb20 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2eb30 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2eb40 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2eb50 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2eb60 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2eb70 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2eb80 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2eb90 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2eba0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2ebb0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2ebc0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2ebd0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2ebe0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2ebf0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2ec00 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2ec10 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2ec20 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2ec30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2ec40 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
2ec50 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2ec60 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2ec70 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ec80 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2ec90 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2eca0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2ecb0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2ecc0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2ecd0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2ece0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2ecf0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2ed00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2ed10 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2ed20 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2ed30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2ed40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2ed50 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2ed60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ed70 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2ed80 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2ed90 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2eda0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2edb0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2edc0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
2edd0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
2ede0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2edf0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2ee00 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ee10 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2ee20 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2ee30 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2ee40 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2ee50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2ee60 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2ee70 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2ee80 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2ee90 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2eea0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2eeb0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2eec0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2eed0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2eee0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2eef0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
2ef00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2ef10 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2ef20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2ef30 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2ef40 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2ef50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2ef60 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2ef70 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2ef80 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2ef90 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2efa0 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2efb0 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2efc0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2efd0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2efe0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2eff0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2f000 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2f010 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2f020 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2f030 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2f040 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2f050 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2f060 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2f070 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2f080 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2f090 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2f0a0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2f0b0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2f0c0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2f0d0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2f0e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2f0f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2f100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f110 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2f120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f130 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2f140 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2f150 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2f160 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2f170 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2f180 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2f190 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2f1a0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2f1b0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2f1c0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2f1d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f1e0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2f1f0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f200 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2f210 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2f220 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2f230 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2f240 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2f250 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2f260 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2f270 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2f280 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2f290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f2a0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2f2b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f2c0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2f2d0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2f2e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2f2f0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2f300 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2f310 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2f320 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2f330 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2f340 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f350 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2f360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f370 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2f380 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2f390 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2f3a0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2f3b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2f3c0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2f3d0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2f3e0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2f3f0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2f400 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2f410 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2f420 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2f430 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2f440 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2f450 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2f460 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2f470 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2f480 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2f490 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2f4a0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2f4b0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2f4c0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2f4d0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2f4e0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2f4f0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2f500 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2f510 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2f520 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2f530 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2f540 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2f550 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2f560 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2f570 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2f580 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2f590 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2f5a0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2f5b0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2f5c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2f5d0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2f5e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f5f0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2f600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f610 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2f620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f630 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2f640 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2f650 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2f660 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f670 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f680 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2f690 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2f6a0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2f6b0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2f6c0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2f6d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f6e0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2f6f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f700 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2f710 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2f720 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2f730 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2f740 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2f750 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2f760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f770 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2f780 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2f790 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2f7a0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2f7b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f7c0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2f7d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2f7e0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2f7f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f800 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2f810 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2f820 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2f830 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2f840 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2f850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f860 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2f870 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2f880 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2f890 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f8a0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2f8b0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2f8c0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2f8d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2f8e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f8f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2f900 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2f910 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2f920 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2f930 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2f940 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2f950 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2f960 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2f970 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2f980 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2f990 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
2f9a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2f9b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f9c0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2f9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2f9e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2f9f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2fa00 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2fa10 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2fa20 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2fa30 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2fa40 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2fa50 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2fa60 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2fa70 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2fa80 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2fa90 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2faa0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2fab0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2fac0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2fad0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2fae0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2faf0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2fb00 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2fb10 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2fb20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2fb30 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2fb40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2fb50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb60 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2fb70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2fb80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2fb90 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2fba0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fbb0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2fbc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2fbd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2fbe0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2fbf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2fc00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2fc10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2fc20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2fc40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fc50 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2fc60 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2fc70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fc80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2fc90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2fca0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2fcb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2fcc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fcd0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2fce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2fcf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fd00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2fd10 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2fd20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2fd30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fd40 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2fd50 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2fd60 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2fd70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2fd80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fd90 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2fda0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2fdb0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2fdc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2fdd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2fde0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2fdf0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2fe00 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2fe10 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2fe20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2fe30 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2fe40 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2fe50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fe60 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2fe70 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2fe80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2fe90 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2fea0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2feb0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2fec0 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2fed0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2fee0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2fef0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2ff00 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2ff10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ff20 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2ff30 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2ff40 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2ff50 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2ff60 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2ff70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ff80 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2ff90 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2ffa0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2ffb0 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2ffc0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2ffd0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2ffe0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2fff0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
30000 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
30010 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
30020 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
30030 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
30040 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
30050 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
30060 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
30070 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
30080 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
30090 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
300a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
300b0 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
300c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
300d0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
300e0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
300f0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
30100 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
30110 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
30120 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
30130 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
30140 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
30150 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
30160 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
30170 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
30180 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
30190 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
301a0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
301b0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
301c0 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
301d0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
301e0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
301f0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
30200 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
30210 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
30220 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30230 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30240 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
30250 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
30260 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
30270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
30280 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
30290 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
302a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
302b0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
302c0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
302d0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
302e0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
302f0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
30300 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
30310 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
30320 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
30330 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
30340 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
30350 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
30360 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
30370 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
30380 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
30390 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
303a0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
303b0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
303c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
303d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
303e0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
303f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
30400 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
30410 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
30420 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
30430 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30440 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30450 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
30460 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
30470 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
30480 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
30490 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
304a0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
304b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
304c0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
304d0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
304e0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
304f0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
30500 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30510 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
30520 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
30530 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30540 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
30550 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30560 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
30570 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
30580 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
30590 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
305a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
305b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
305c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
305d0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
305e0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
305f0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
30600 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
30610 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
30620 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
30630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30640 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
30650 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
30660 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
30670 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30680 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
30690 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
306a0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
306b0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
306c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
306d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
306e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
306f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
30700 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
30710 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30720 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
30730 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
30740 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
30750 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
30760 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
30770 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
30780 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
30790 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
307a0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
307b0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
307c0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
307d0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
307e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
307f0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
30800 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
30810 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
30820 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
30830 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
30840 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
30850 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
30860 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
30870 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
30880 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
30890 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
308a0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
308b0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
308c0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
308d0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
308e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
308f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
30900 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30910 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
30920 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
30930 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
30940 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
30950 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
30960 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
30970 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
30980 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
30990 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
309a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
309b0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
309c0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
309d0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
309e0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
309f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
30a00 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
30a10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30a20 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
30a30 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
30a40 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
30a50 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
30a60 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
30a70 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
30a80 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
30a90 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
30aa0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
30ab0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
30ac0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
30ad0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
30ae0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
30af0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
30b00 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
30b10 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
30b20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
30b30 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
30b40 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
30b50 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
30b60 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
30b70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
30b80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
30b90 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
30ba0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
30bb0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
30bc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
30bd0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
30be0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
30bf0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
30c00 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
30c10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
30c20 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
30c30 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
30c40 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
30c50 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
30c60 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
30c70 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
30c80 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
30c90 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
30ca0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
30cb0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
30cc0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
30cd0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
30ce0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
30cf0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30d00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
30d10 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
30d20 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
30d30 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
30d40 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
30d50 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
30d60 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
30d70 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
30d80 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
30d90 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
30da0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
30db0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
30dc0 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
30dd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30de0 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
30df0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30e00 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
30e10 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
30e20 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
30e30 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
30e40 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
30e50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30e60 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
30e70 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
30e80 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
30e90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30ea0 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
30eb0 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
30ec0 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
30ed0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
30ee0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
30ef0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
30f00 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
30f10 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
30f20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
30f30 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
30f40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
30f50 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
30f60 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
30f70 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
30f80 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
30f90 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
30fa0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
30fb0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
30fc0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
30fd0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
30fe0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
30ff0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
31000 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
31010 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
31020 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
31030 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
31040 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
31050 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
31060 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
31070 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
31080 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
31090 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
310a0 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
310b0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
310c0 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
310d0 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
310e0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
310f0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
31100 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
31110 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
31120 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
31130 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
31140 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
31150 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
31160 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
31170 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
31180 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
31190 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
311a0 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
311b0 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
311c0 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
311d0 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
311e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
311f0 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
31200 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
31210 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
31220 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
31230 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
31240 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
31250 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
31260 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
31270 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
31280 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
31290 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
312a0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
312b0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
312c0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
312d0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
312e0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
312f0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
31300 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
31310 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
31320 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
31330 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
31340 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
31350 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
31360 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
31370 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
31380 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
31390 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
313a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
313b0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
313c0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
313d0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
313e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
313f0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
31400 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
31410 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
31420 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
31430 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
31440 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
31450 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
31460 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
31470 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
31480 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
31490 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
314a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
314b0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
314c0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
314d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
314e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
314f0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
31500 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
31510 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
31520 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
31530 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
31540 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
31550 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
31560 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
31570 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
31580 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
31590 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
315a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
315b0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
315c0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
315d0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
315e0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
315f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
31600 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
31610 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
31620 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
31630 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
31640 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
31650 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
31660 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
31670 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
31680 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
31690 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
316a0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
316b0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
316c0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
316d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
316e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
316f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
31700 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
31710 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
31720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31730 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
31740 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
31750 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
31760 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
31770 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
31780 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
31790 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
317a0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
317b0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
317c0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
317d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
317e0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
317f0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
31800 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
31810 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
31820 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
31830 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31840 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
31850 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
31860 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
31870 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
31880 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
31890 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
318a0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
318b0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
318c0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
318d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
318e0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
318f0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
31900 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
31910 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
31920 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
31930 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
31940 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
31950 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
31960 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
31970 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
31980 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
31990 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
319a0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
319b0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
319c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
319d0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
319e0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
319f0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
31a00 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
31a10 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
31a20 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
31a30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31a40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
31a50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31a60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
31a70 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
31a80 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
31a90 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
31aa0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
31ab0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
31ac0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
31ad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
31ae0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
31af0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
31b00 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
31b10 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
31b20 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31b30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
31b40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
31b50 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
31b60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
31b70 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
31b80 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
31b90 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
31ba0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
31bb0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
31bc0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31bd0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31be0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
31bf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31c00 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31c10 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
31c20 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31c30 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
31c40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31c50 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
31c60 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
31c70 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
31c80 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
31c90 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31ca0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
31cb0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
31cc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31cd0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
31ce0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
31cf0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
31d00 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31d10 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31d20 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
31d30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
31d40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
31d50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
31d60 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
31d70 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31d80 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
31d90 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
31da0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
31db0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31dc0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31dd0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31de0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31df0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31e10 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31e20 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31e30 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31e40 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
31e50 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
31e60 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
31e70 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
31e80 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
31e90 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
31ea0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
31eb0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
31ec0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
31ed0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
31ee0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
31ef0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
31f00 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
31f10 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
31f20 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
31f30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
31f40 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
31f50 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
31f60 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
31f70 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
31f80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31f90 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
31fa0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
31fb0 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
31fc0 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
31fd0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
31fe0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
31ff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32000 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
32010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32020 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
32030 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32040 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
32050 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
32060 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
32070 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
32080 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
32090 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
320a0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
320b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
320c0 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
320d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
320e0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
320f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32100 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
32110 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32120 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
32130 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
32140 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
32150 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
32160 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
32170 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32180 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
32190 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
321a0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
321b0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
321c0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
321d0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
321e0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
321f0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
32200 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
32210 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
32220 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
32230 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
32240 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
32250 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
32260 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
32270 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
32280 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
32290 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
322a0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
322b0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
322c0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
322d0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
322e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
322f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
32300 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
32310 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
32320 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32330 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
32340 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32350 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32360 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
32370 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
32380 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
32390 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
323a0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
323b0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
323c0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
323d0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
323e0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
323f0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
32400 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
32410 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32420 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
32430 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
32440 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
32450 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
32460 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
32470 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
32480 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
32490 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
324a0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
324b0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
324c0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
324d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
324e0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
324f0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
32500 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
32510 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
32520 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
32530 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
32540 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
32550 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
32560 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
32570 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
32580 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
32590 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
325a0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
325b0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
325c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
325d0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
325e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
325f0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
32600 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
32610 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
32620 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32630 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
32640 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
32650 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
32660 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
32670 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
32680 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
32690 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
326a0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
326b0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
326c0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
326d0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
326e0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
326f0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
32700 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
32710 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
32720 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
32730 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32740 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
32750 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
32760 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
32770 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32780 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
32790 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
327a0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
327b0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
327c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
327d0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
327e0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
327f0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
32800 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
32810 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
32820 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
32830 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
32840 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
32850 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
32860 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
32870 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
32880 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32890 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
328a0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
328b0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
328c0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
328d0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
328e0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
328f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
32900 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
32910 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
32920 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
32930 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
32940 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
32950 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
32960 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
32970 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
32980 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
32990 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
329a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
329b0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
329c0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
329d0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
329e0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
329f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
32a00 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
32a10 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
32a20 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
32a30 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
32a40 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
32a50 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
32a60 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
32a70 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
32a80 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
32a90 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
32aa0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
32ab0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
32ac0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
32ad0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
32ae0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
32af0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
32b00 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
32b10 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
32b20 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
32b30 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
32b40 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
32b50 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
32b60 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
32b70 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
32b80 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
32b90 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
32ba0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
32bb0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
32bc0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
32bd0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
32be0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
32bf0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
32c00 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
32c10 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
32c20 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
32c30 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32c40 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
32c50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32c60 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
32c70 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
32c80 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
32c90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
32ca0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
32cb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32cc0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
32cd0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
32ce0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32cf0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32d00 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
32d10 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
32d20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32d30 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
32d40 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
32d50 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
32d60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
32d70 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
32d80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
32d90 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
32da0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
32db0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
32dc0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
32dd0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32de0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32df0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
32e00 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
32e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
32e20 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
32e30 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
32e40 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
32e50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
32e60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
32e70 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
32e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32e90 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
32ea0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
32eb0 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
32ec0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
32ed0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32ee0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
32ef0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
32f00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
32f10 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
32f20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
32f30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32f40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
32f50 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
32f60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
32f70 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
32f80 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
32f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
32fa0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
32fb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
32fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
32fd0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
32fe0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
32ff0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
33000 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
33010 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
33020 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
33030 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
33040 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
33050 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
33060 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
33070 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
33080 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33090 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
330a0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
330b0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
330c0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
330d0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
330e0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
330f0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
33100 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
33110 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
33120 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
33130 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
33140 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
33150 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
33160 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33170 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
33180 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
33190 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
331a0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
331b0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
331c0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
331d0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
331e0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
331f0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
33200 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
33210 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
33220 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
33230 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
33240 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
33250 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33260 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
33270 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
33280 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
33290 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
332a0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
332b0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
332c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
332d0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
332e0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
332f0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
33300 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
33310 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
33320 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33330 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
33340 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
33350 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
33360 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
33370 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
33380 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33390 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
333a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
333b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
333c0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
333d0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
333e0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
333f0 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
33400 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
33410 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
33420 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
33430 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
33440 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
33450 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33460 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
33470 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
33480 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
33490 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
334a0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
334b0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
334c0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
334d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
334e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
334f0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
33500 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
33510 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
33520 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
33530 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
33540 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
33550 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
33560 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
33570 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
33580 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
33590 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
335a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
335b0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
335c0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
335d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
335e0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
335f0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
33600 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
33610 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
33620 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
33630 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33640 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
33650 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
33660 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
33670 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33680 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
33690 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
336a0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
336b0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
336c0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
336d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
336e0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
336f0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
33700 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
33710 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
33720 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
33730 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
33740 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
33750 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
33760 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
33770 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
33780 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
33790 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
337a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
337b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
337c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
337d0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
337e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
337f0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
33800 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
33810 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
33820 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
33830 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
33840 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
33850 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
33860 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
33870 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
33880 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
33890 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
338a0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
338b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
338c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
338d0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
338e0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
338f0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
33900 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
33910 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
33920 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
33930 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
33940 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
33950 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
33960 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33970 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33980 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33990 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
339a0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
339b0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
339c0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
339d0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
339e0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
339f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33a00 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
33a10 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
33a20 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
33a30 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
33a40 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
33a50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
33a60 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
33a70 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
33a80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33a90 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
33aa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33ab0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
33ac0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
33ad0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
33ae0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
33af0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
33b00 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
33b10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
33b20 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
33b30 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
33b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33b50 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
33b60 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73   Data.**.** Thes
33b70 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
33b80 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
33b90 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
33ba0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
33bb0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
33bc0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
33bd0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
33be0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
33bf0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
33c00 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
33c10 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
33c20 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
33c30 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
33c40 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
33c50 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
33c60 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
33c70 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
33c80 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
33c90 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
33ca0 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
33cb0 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
33cc0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
33cd0 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
33ce0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
33cf0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
33d00 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
33d10 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
33d20 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
33d30 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
33d40 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
33d50 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
33d60 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
33d70 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
33d80 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
33d90 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
33da0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
33db0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
33dc0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
33dd0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33de0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
33df0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33e00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
33e10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33e20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
33e30 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
33e40 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
33e50 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
33e60 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
33e70 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
33e80 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
33e90 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
33ea0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33eb0 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
33ec0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
33ed0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
33ee0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
33ef0 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
33f00 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33f10 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
33f20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
33f30 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
33f40 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
33f50 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
33f60 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
33f70 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
33f80 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
33f90 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
33fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33fb0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
33fc0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
33fd0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
33fe0 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
33ff0 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
34000 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
34010 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34020 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
34030 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
34040 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
34050 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
34060 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
34070 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
34080 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
34090 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
340a0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
340b0 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
340c0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
340d0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
340e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
340f0 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
34100 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
34110 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
34120 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
34130 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
34140 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
34150 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
34160 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
34170 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
34180 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
34190 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
341a0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
341b0 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
341c0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
341d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
341e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
341f0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
34200 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
34210 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
34220 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
34230 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34240 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
34250 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
34260 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
34270 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
34280 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
34290 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
342a0 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
342b0 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
342c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
342d0 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
342e0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
342f0 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
34300 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
34310 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
34320 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
34330 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
34340 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
34350 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
34360 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
34370 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34380 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
34390 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
343a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
343b0 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
343c0 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
343d0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
343e0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
343f0 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
34400 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
34410 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
34420 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
34430 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
34440 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34450 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
34460 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
34470 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
34480 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
34490 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
344a0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
344b0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
344c0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
344d0 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
344e0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
344f0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
34500 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
34510 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
34520 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
34530 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
34540 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
34550 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34560 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34570 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
34580 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34590 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
345a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
345b0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
345c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
345d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
345e0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
345f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34600 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
34610 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
34620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34630 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
34640 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
34650 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
34660 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
34670 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
34680 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
34690 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
346a0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
346b0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
346c0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
346d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
346e0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
346f0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
34700 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
34710 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
34720 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
34730 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
34740 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
34750 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
34760 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
34770 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
34780 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
34790 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
347a0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
347b0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
347c0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
347d0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
347e0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
347f0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
34800 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
34810 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
34820 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
34830 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
34840 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
34850 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
34860 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
34870 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
34880 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74   compilers..*/.t
34890 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
348a0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
348b0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
348c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
348d0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
348e0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
348f0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
34900 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
34910 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
34920 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
34930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34940 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
34950 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
34960 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
34970 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34980 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
34990 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
349a0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
349b0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
349c0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
349d0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
349e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
349f0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
34a00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34a10 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
34a20 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
34a30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
34a40 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
34a50 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
34a60 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
34a70 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
34a80 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
34a90 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
34aa0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
34ab0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
34ac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34ad0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
34ae0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
34af0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
34b00 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
34b10 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
34b20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34b30 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
34b40 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34b50 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
34b60 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
34b70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34b80 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
34b90 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
34ba0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
34bb0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34bc0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
34bd0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
34be0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
34bf0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
34c00 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
34c10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
34c20 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
34c30 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
34c40 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
34c50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34c60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
34c70 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
34c80 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
34c90 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
34ca0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
34cb0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
34cc0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34cd0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
34ce0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
34cf0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
34d00 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
34d10 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
34d20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34d30 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34d40 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
34d50 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
34d60 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
34d70 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34d80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34d90 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
34da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34db0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
34dc0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
34dd0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
34de0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
34df0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
34e00 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
34e10 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
34e20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
34e30 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
34e40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34e50 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
34e60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34e70 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
34e80 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
34e90 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
34ea0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
34eb0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
34ec0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
34ed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
34ee0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
34ef0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
34f00 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
34f10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34f20 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
34f30 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
34f40 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
34f50 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
34f60 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34f70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
34f80 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34f90 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
34fa0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
34fb0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
34fc0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
34fd0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
34fe0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
34ff0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
35000 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
35010 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
35020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35030 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
35040 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35050 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
35060 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
35070 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
35080 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
35090 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
350a0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
350b0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
350c0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
350d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
350e0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
350f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35100 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
35110 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
35120 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
35130 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
35140 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
35150 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
35160 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
35170 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
35180 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
35190 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
351a0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
351b0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
351c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
351d0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
351e0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
351f0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
35200 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
35210 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
35220 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
35230 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
35240 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
35250 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
35260 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
35270 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
35280 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
35290 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
352a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
352b0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
352c0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
352d0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
352e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
352f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
35300 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
35310 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
35320 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
35330 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
35340 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
35350 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
35360 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
35370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35390 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
353a0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
353b0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
353c0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
353d0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
353e0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
353f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35400 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
35410 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35420 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35430 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
35440 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35450 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
35460 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
35470 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
35480 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
35490 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
354a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
354b0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
354c0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
354d0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
354e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
354f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35500 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
35510 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
35520 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
35530 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
35540 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
35550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35560 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
35570 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35580 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35590 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
355a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
355b0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
355c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
355d0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
355e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
355f0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
35600 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
35610 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
35620 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
35630 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
35640 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
35650 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
35660 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35670 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
35680 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
35690 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
356a0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
356b0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
356c0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
356d0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
356e0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
356f0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
35700 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ely..** ^The sql
35710 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35720 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
35730 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35740 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70  alue of an.** ap
35750 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35760 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35770 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69   a text string i
35780 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  n an encoding.**
35790 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
357a0 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73  e fifth (and las
357b0 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  t) parameter, wh
357c0 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a  ich must be one.
357d0 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ** of [SQLITE_UT
357e0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
357f0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
35800 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
35810 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e  E_UTF16LE]..** ^
35820 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
35830 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
35840 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
35850 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
35860 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
35870 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35880 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35890 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
358a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
358b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
358c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
358d0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
358e0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
358f0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
35900 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
35910 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
35920 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
35930 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
35940 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
35950 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
35960 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35970 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
35980 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
35990 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
359a0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
359b0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
359c0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
359d0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
359e0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
359f0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
35a00 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
35a10 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
35a20 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
35a30 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
35a40 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
35a50 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
35a60 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
35a70 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
35a80 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
35a90 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
35aa0 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
35ab0 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
35ac0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
35ad0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
35ae0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
35af0 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
35b00 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
35b10 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
35b20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
35b30 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
35b40 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
35b50 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
35b60 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
35b70 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
35b80 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
35b90 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
35ba0 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
35bb0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
35bc0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
35bd0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35be0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35bf0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35c00 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
35c10 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
35c20 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
35c30 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
35c40 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
35c50 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
35c60 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
35c70 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
35c80 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
35c90 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
35ca0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
35cb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35cc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35cd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35ce0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35cf0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
35d00 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35d10 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35d20 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
35d30 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
35d40 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
35d50 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
35d60 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
35d70 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
35d80 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
35d90 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
35da0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
35db0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
35dc0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
35dd0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
35de0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
35df0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
35e00 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35e10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35e20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35e30 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35e40 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
35e50 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
35e60 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
35e70 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
35e80 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
35e90 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
35ea0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
35eb0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
35ec0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
35ed0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35ee0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
35ef0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
35f00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35f10 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
35f20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
35f30 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
35f40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35f50 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
35f60 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
35f70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35f80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
35f90 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
35fa0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
35fb0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
35fc0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
35fd0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
35fe0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
35ff0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
36000 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
36010 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
36020 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
36030 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
36040 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
36050 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
36060 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36070 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
36080 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
36090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
360a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
360b0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
360c0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
360d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
360e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
360f0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
36100 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
36110 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
36120 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
36130 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
36140 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
36150 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
36160 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
36170 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
36180 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
36190 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
361a0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
361b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
361c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
361d0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
361e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
361f0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
36200 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
36210 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
36220 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36230 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
36240 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36250 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36260 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36270 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36280 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
36290 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  xt*,const void*,
362a0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
362b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
362c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
362d0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
362e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
362f0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
36300 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36310 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36320 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36330 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
36340 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36350 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36360 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36370 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36390 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
363a0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
363b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
363c0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
363d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
363e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
363f0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
36400 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36410 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36420 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
36430 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36440 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36450 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
36460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36470 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
36480 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36490 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
364a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
364b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
364c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
364d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
364e0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
364f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36510 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt64(sqlite3_con
36520 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36530 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
36540 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
36550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
36560 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
36570 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
36580 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ding);.void sqli
36590 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
365a0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
365b0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
365c0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
365d0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
365e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
365f0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
36600 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
36610 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
36620 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36630 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36640 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
36650 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36660 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
36670 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36680 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36690 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
366a0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
366b0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
366c0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
366d0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
366e0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
366f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
36700 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
36710 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
36720 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
36730 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
36740 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
36750 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
36760 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
36770 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36780 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
36790 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
367a0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
367b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
367c0 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
367d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
367e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
367f0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
36800 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36810 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
36820 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
36830 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
36840 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
36850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36860 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
36870 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
36880 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
36890 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
368a0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
368b0 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
368c0 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
368d0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
368e0 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
368f0 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
36900 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
36910 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
36920 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
36930 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
36940 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
36950 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
36960 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
36970 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
36980 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
36990 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
369a0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
369b0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
369c0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
369d0 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
369e0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
369f0 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
36a00 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
36a10 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
36a20 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
36a30 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
36a40 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
36a50 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
36a60 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
36a70 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
36a80 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
36a90 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
36aa0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
36ab0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
36ac0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
36ad0 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
36ae0 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
36af0 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
36b00 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
36b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
36b20 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
36b30 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
36b40 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
36b50 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
36b60 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
36b70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
36b80 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
36b90 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
36ba0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
36bb0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
36bc0 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
36bd0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
36be0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36bf0 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
36c00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36c10 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
36c20 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
36c30 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
36c40 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
36c50 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
36c60 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
36c70 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
36c80 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
36c90 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
36ca0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
36cb0 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
36cc0 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
36cd0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
36ce0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
36cf0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36d00 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
36d10 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
36d20 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36d30 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
36d40 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
36d50 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
36d60 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
36d70 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
36d80 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
36d90 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
36da0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
36db0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
36dc0 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
36dd0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
36de0 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
36df0 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
36e00 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
36e10 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
36e20 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
36e30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36e40 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
36e50 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
36e60 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
36e70 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
36e80 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
36e90 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
36ea0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
36eb0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
36ec0 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
36ed0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
36ee0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36ef0 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
36f00 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
36f10 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
36f20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
36f30 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
36f40 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36f50 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
36f60 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
36f70 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
36f80 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
36f90 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
36fa0 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
36fb0 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
36fc0 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
36fd0 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
36fe0 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
36ff0 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
37000 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
37010 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
37020 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
37030 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
37040 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
37050 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
37060 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
37070 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
37080 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
37090 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
370a0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
370b0 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
370c0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
370d0 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
370e0 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
370f0 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
37100 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
37110 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
37120 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
37130 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
37140 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37150 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
37160 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
37170 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
37180 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
37190 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
371a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
371b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
371c0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
371d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
371e0 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
371f0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
37200 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
37210 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
37220 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
37230 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37240 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
37250 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
37260 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
37270 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
37280 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
37290 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
372a0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
372b0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
372c0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
372d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
372e0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
372f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
37300 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
37310 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
37320 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
37330 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
37340 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
37350 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37360 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
37370 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
37380 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
37390 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
373a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
373b0 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
373c0 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
373d0 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
373e0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
373f0 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
37400 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37410 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
37420 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
37430 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
37440 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
37450 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
37460 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
37470 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
37480 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
37490 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
374a0 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
374b0 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
374c0 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
374d0 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
374e0 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
374f0 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
37500 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
37510 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
37520 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37530 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
37540 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37550 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
37560 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37570 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
37580 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37590 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
375a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
375b0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
375c0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
375d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
375e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
375f0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
37600 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37610 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
37620 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
37630 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
37640 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37650 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37660 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37670 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37680 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37690 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
376a0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
376b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
376c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
376d0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
376e0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
376f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
37700 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
37710 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
37720 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37730 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37740 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
37750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
37760 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
37770 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
37780 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
37790 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
377a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
377b0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
377c0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
377d0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
377e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
377f0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
37800 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
37810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37820 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
37830 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
37840 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
37850 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
37860 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
37870 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
37880 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
37890 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
378a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
378b0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
378c0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
378d0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
378e0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
378f0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
37900 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
37910 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
37920 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37930 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
37940 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
37950 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
37960 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
37970 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37980 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
37990 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
379a0 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
379b0 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
379c0 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
379d0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
379e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
379f0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
37a00 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
37a10 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
37a20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
37a30 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
37a40 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37a50 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
37a60 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37a70 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
37a80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
37a90 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
37aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
37ab0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
37ac0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
37ad0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
37ae0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
37af0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
37b00 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
37b10 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
37b20 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
37b30 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
37b40 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
37b50 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
37b60 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
37b70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
37b80 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
37b90 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
37ba0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
37bb0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
37bc0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
37bd0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
37be0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
37bf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37c00 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
37c10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37c20 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
37c30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37c40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
37c50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37c60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37c70 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
37c80 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
37c90 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
37ca0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
37cb0 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
37cc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
37cd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
37ce0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
37cf0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
37d00 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
37d10 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
37d20 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
37d30 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
37d40 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
37d50 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
37d60 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
37d70 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
37d80 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
37d90 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
37da0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
37db0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
37dc0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
37dd0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
37de0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
37df0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
37e00 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
37e10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
37e20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37e40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
37e50 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
37e60 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37e70 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37e80 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37e90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  ;.int sqlite3_ke
37ea0 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
37eb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37ec0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37ed0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
37ee0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37ef0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37f00 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
37f10 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
37f20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37f30 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37f40 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37f50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
37f60 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
37f70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
37f80 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
37f90 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
37fa0 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
37fb0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
37fc0 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
37fd0 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
37fe0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
37ff0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
38000 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
38010 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
38020 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
38030 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
38040 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
38050 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
38060 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
38070 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
38080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38090 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
380a0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
380b0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
380c0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
380d0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
380e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  );.int sqlite3_r
380f0 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  ekey_v2(.  sqlit
38100 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
38110 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
38120 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
38130 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
38140 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
38150 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
38160 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
38170 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
38180 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
38190 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
381a0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
381b0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
381c0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
381d0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
381e0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
381f0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
38200 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
38210 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
38220 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
38230 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
38240 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
38250 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
38260 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
38270 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
38280 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
38290 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
382a0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
382b0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
382c0 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
382d0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
382e0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
382f0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
38300 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
38310 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
38320 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
38330 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
38340 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
38350 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
38360 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
38370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
38380 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
38390 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
383a0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
383b0 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
383c0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
383d0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
383e0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
383f0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
38400 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
38410 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
38420 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
38430 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
38440 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
38450 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
38460 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
38470 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
38480 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
38490 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
384a0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
384b0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
384c0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
384d0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
384e0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
384f0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
38500 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
38510 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
38520 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
38530 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
38540 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
38550 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
38560 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
38570 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
38580 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
38590 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
385a0 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
385b0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
385c0 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
385d0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
385e0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
385f0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
38600 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
38610 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
38620 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
38630 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
38640 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
38650 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
38660 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
38670 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
38680 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
38690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
386a0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
386b0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
386c0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
386d0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
386e0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
386f0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
38700 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
38710 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
38720 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
38730 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
38740 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
38750 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
38760 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
38770 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
38780 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
38790 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
387a0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
387b0 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
387c0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
387d0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
387e0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
387f0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
38800 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
38810 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
38820 72 61 72 79 20 66 69 6c 65 20 64 6