/ Hex Artifact Content
Login

Artifact ed6d0cc90da850340c3863c84351e6e164c0ef00:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
63c0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
63d0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
63e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
63f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6400: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6410: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6420: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6430: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6440: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6450: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
6460: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
6470: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6480: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6490: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
64a0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
64b0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
64c0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
64e0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
64f0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6510: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6520: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6530: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6540: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6570: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6580: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6590: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
65a0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
65b0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
65c0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
65d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
65e0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
65f0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6610: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6620: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6630: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6640: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6650: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6660: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6670: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6680: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6690: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
66a0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
66b0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
66c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
66d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66e0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
66f0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6700: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6710: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6720: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6740: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6750: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6760: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6770: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6780: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6790: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
67a0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
67b0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
67c0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
67d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
67e0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
67f0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6800: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6810: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6830: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6840: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6850: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6860: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6870: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6880: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6890: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
68a0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
68b0: 68 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64 65  hen open..*/.#de
68c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
68d0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
68e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68f0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6900: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6910: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6920: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6930: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6940: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6950: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6960: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6970: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6990: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
69a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
69b0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
69c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
69d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a00: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6a10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6a20: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6a30: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a50: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6a60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a70: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
6a80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a90: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
6aa0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
6ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ac0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
6ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6ae0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6af0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6b00: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6b10: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6b20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6b30: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6b40: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b60: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6b70: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6b80: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0001000../*.** C
6b90: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6ba0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6bb0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6bc0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6bd0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6be0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6bf0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6c00: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6c10: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6c20: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6c30: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6c40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6c50: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6c60: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6c70: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6c80: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6c90: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6cb0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6cd0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6ce0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6cf0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6d00: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6d10: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6d20: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6d30: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6d40: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6d50: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6d60: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6d70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d80: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6d90: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6da0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6db0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6dc0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6dd0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6de0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6df0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6e00: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6e10: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6e20: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6e30: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6e40: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6e50: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6e60: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6e70: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6e80: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6e90: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6ea0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6eb0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6ec0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6ed0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6ee0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6ef0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6f00: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6f10: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6f20: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6f30: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6f40: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6f50: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6f60: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6f70: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6f80: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6f90: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6fa0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6fb0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6fc0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6fd0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6fe0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6ff0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7000: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7010: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7020: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7030: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7040: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
7050: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
7060: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
7070: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7080: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7090: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
70a0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
70b0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
70c0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
70d0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
70e0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
70f0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7100: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7110: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7120: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7130: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7140: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
7150: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
7160: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
7170: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7180: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7190: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
71a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
71b0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
71c0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
71d0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
71e0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
71f0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7200: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7210: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7230: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7240: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
7250: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
7260: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
7270: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7280: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7290: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
72a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
72b0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
72c0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
72d0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
72e0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
72f0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7300: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7310: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7320: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7330: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7340: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7350: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7360: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7370: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7380: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7390: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
73a0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
73b0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
73c0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
73d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
73e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
73f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7400: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7410: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7420: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7430: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7440: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7450: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7460: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7470: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7480: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7490: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
74a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
74b0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
74c0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
74d0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
74e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
74f0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7500: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7510: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7520: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7530: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7540: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7550: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7560: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7570: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7580: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7590: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
75a0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
75b0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
75c0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
75d0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
75e0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
75f0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7600: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7610: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7620: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7630: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7640: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7650: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7660: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7670: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7680: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7690: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
76a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
76b0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
76c0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
76d0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
76e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
76f0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7700: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7710: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7720: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7730: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7740: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7750: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7760: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7770: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7780: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7790: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
77a0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
77b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77c0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
77d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
77e0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
77f0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7800: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7810: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7820: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7830: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7840: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7850: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7860: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7870: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7880: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7890: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
78a0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
78b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
78c0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
78d0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
78e0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
78f0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7900: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7910: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7920: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7930: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7940: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7950: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7960: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7970: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
7980: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7990: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
79a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
79b0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
79c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
79d0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
79e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79f0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7a00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7a10: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7a20: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7a30: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7a40: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
7a50: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
7a60: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
7a70: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
7a80: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
7a90: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
7aa0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7ab0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7ac0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7ad0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7ae0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7af0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7b00: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7b10: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7b20: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7b30: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7b40: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7b50: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7b60: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7b70: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7b80: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7b90: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7ba0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7bb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7bc0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7bd0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7be0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7bf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7c00: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7c10: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7c20: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7c30: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7c40: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7c50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7c60: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7c70: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7c80: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7c90: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7ca0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7cb0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7cc0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7cd0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7ce0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7cf0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7d00: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7d10: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7d20: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7d30: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7d40: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7d50: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7d60: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7d70: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7d80: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7d90: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7da0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7db0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7dc0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7dd0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7de0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7df0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7e00: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7e10: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7e20: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7e30: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7e40: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7e50: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7e60: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7e70: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7e80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7e90: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7ea0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7eb0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7ec0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7ed0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7ee0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7ef0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7f00: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7f10: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7f20: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7f30: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7f40: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7f50: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7f60: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7f70: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7f80: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7f90: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7fa0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7fb0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7fc0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7fd0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7fe0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7ff0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8000: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8010: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8020: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8030: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8040: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8050: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8060: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8070: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
8080: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <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 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
80b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80c0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
80d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80e0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
80f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8100: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8120: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8130: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8140: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8170: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8180: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
8190: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
81a0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
81b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
81c0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
81d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81e0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
81f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8210: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8220: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8230: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8240: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8260: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8270: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8280: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
8290: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
82a0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
82b0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
82c0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
82d0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
82e0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
82f0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8300: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8310: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8320: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8330: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8340: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8350: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8360: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8370: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8380: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
8390: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
83a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
83b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
83c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
83d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
83e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
83f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8400: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8410: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8420: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8430: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8440: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8450: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8460: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8470: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8480: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
8490: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
84a0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
84b0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
84c0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
84d0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
84e0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
84f0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8500: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8510: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8520: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8530: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8540: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8550: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8570: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8580: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
85a0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
85b0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
85c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
85d0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
85e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
85f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8600: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8610: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8620: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8630: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8640: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8650: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8660: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8690: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
86a0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
86b0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
86c0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
86d0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
86e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
86f0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8700: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8710: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8720: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8730: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8740: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8750: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8760: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8770: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8780: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
8790: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
87a0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
87b0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
87c0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
87d0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
87e0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
87f0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8800: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8810: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8820: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8830: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8840: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8860: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8870: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8880: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
8890: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
88a0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
88b0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
88c0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
88d0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
88e0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
88f0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8900: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8910: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8920: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8930: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8940: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8950: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8970: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8980: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
8990: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
89a0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
89b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
89c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
89d0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
89e0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
89f0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8a00: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8a10: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8a20: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8a30: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8a40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8a50: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8a60: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8a80: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8a90: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8aa0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8ab0: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8ac0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8ad0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
8ae0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
8af0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b00: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
8b10: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8b20: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8b40: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8b50: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8b60: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8b70: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8b80: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8b90: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8ba0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8bb0: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8bc0: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8bd0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8be0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8bf0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8c00: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8c10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8c20: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8c30: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8c40: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8c50: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8c60: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8c70: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8c80: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
8c90: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
8ca0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
8cb0: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
8cc0: 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a  efined..** <ul>.
8cd0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8ce0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8cf0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d00: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8d10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d20: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8d30: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d40: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8d50: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8d60: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8d70: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8d80: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8d90: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8da0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8db0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8dc0: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8dd0: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8de0: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8df0: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8e00: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8e10: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8e20: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8e30: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e40: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8e50: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8e60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8e70: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8e80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e90: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8ea0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8eb0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8ec0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8ed0: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8ee0: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8ef0: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8f00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8f10: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8f20: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8f30: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f40: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8f50: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8f60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8f70: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8f80: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8f90: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8fa0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8fb0: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8fc0: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8fd0: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8fe0: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8ff0: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9000: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9010: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9020: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9030: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9040: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9050: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9060: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
9070: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
9080: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
9090: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
90a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
90b0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
90c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
90d0: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
90e0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
90f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9100: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9110: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9130: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9140: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
9150: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
9160: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9170: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
9180: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
91b0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
91c0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
91d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
91e0: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
91f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9200: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9210: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9220: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9230: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9240: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9250: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9260: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9270: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9280: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9290: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
92a0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
92b0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
92c0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
92d0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
92e0: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
92f0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9300: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9310: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9320: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9330: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9340: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9350: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9360: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9370: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9380: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9390: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
93a0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
93b0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
93c0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
93d0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
93e0: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
93f0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9400: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9410: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9420: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9430: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9440: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9450: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9460: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9470: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9480: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9490: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
94a0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
94b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
94c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
94d0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
94e0: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
94f0: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9500: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9510: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9520: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9530: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9540: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9560: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9570: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9580: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9590: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
95a0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
95b0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
95c0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
95d0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
95e0: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
95f0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9600: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9610: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9620: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9630: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9640: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9650: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9660: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9670: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9680: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9690: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
96a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
96b0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
96c0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
96d0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
96e0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
96f0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9700: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9710: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9720: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9730: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9740: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9750: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9760: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9770: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9780: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9790: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
97a0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
97b0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
97c0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
97d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
97e0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
97f0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9800: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9810: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9820: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9830: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9840: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9850: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9860: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9870: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9880: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9890: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
98a0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
98b0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
98c0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
98d0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
98e0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
98f0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9900: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9910: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9920: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9930: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9940: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9950: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9960: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9970: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9980: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9990: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
99a0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
99b0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
99c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99d0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
99e0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
99f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9a00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9a10: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9a20: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9a30: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a40: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9a50: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9a60: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9a70: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9a80: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9a90: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9aa0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ab0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ac0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ad0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9ae0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9af0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9b00: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9b10: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9b20: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9b30: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b40: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9b50: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9b60: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9b70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9b80: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9b90: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9ba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9bb0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9bc0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9bd0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9be0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9bf0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9c00: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9c10: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9c20: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9c30: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c40: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9c50: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9c60: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9c70: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9c80: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9c90: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9ca0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9cb0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9cc0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9cd0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9ce0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9cf0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9d00: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9d10: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9d20: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9d30: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d40: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9d50: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9d60: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9d70: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9d80: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9d90: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9da0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9db0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9dc0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9dd0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9de0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9df0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9e00: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9e10: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9e20: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9e30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e40: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9e50: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9e60: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9e70: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9e80: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9e90: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ea0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9eb0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9ec0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9ed0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9ee0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9ef0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9f00: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9f10: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9f20: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9f30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f40: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f50: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9f60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9f70: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9f80: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9f90: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9fa0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9fb0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9fc0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9fd0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9fe0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9ff0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a000: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a010: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a020: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a030: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a040: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a050: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a060: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a070: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a080: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a090: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a0a0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a0b0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a0c0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a0d0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a0e0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a0f0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a100: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a110: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a120: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a130: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a140: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a150: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a160: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a170: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a190: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a1b0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a1c0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a1d0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a1e0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a1f0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a200: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a210: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a220: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a230: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a240: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a250: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a260: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a270: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a280: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a290: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a2a0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a2b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a2c0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2e0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a2f0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a300: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a310: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a320: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a330: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a340: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a350: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a360: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a370: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a380: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a390: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a3a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a3b0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a3c0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a3d0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a3e0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a3f0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a400: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a410: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a420: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a430: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a440: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a450: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a460: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a470: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a480: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a490: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a4a0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a4b0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a4c0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a4d0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a4e0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a4f0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a500: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a510: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a520: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a530: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a540: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a550: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a560: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a570: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a580: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a590: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a5a0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a5b0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a5c0: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a5d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a5e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a5f0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a600: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a610: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a620: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a630: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a640: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a650: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a660: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a670: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a690: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a6a0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a6b0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a6c0: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a6d0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a6e0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a6f0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a700: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a710: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a720: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a730: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a740: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a750: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a760: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a770: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a780: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a790: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a7a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a7b0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a7c0: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a7d0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a7e0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a7f0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a800: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a810: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a820: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a830: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a840: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a850: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a860: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a870: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a880: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a890: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a8a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a8c0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a8d0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a8e0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a8f0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a900: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a910: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a940: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a950: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a960: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a970: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a980: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a990: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a9a0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a9b0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a9c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a9d0: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a9e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a9f0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
aa00: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
aa10: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
aa20: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
aa30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
aa40: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
aa50: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
aa60: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aa70: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
aa80: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
aa90: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
aaa0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
aab0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
aac0: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
aad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aae0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
aaf0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
ab00: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
ab10: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
ab20: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
ab30: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
ab40: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
ab50: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
ab60: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
ab70: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab80: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
ab90: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
aba0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
abb0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
abc0: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
abd0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
abe0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
abf0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
ac00: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
ac10: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
ac20: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
ac30: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
ac40: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
ac50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
ac60: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
ac70: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
ac80: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
ac90: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
aca0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
acb0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
acc0: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
acd0: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
ace0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
acf0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
ad00: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
ad10: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
ad30: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
ad40: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
ad50: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
ad60: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
ad70: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
ad80: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
ad90: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
ada0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
adb0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
adc0: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
add0: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
ade0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
adf0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
ae00: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
ae10: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
ae20: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
ae30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ae40: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
ae50: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
ae60: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
ae70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ae80: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
ae90: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
aea0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
aeb0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
aec0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
aed0: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
aee0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
aef0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
af00: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
af10: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
af20: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
af30: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
af40: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
af50: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
af60: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
af70: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
af80: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
af90: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
afa0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
afb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
afc0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
afd0: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
afe0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
aff0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b000: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b010: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b020: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b030: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b040: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b050: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b060: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b070: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b080: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b090: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0a0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b0b0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b0c0: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b0d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b0e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b0f0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b100: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b110: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b120: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b130: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b140: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b150: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b160: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b170: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b180: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b190: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b1a0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b1b0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b1c0: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b1d0: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b1e0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b1f0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b200: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b210: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b220: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b230: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b240: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b250: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b260: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b270: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b280: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b290: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b2a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b2b0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b2c0: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b2d0: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b2e0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b2f0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b300: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b310: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b320: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b330: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b340: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b350: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b360: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b370: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b380: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b390: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b3a0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b3b0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b3c0: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b3d0: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b3e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b3f0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b400: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b410: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b420: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b430: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b440: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b450: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b470: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
b480: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
b490: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
b4a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
b4b0: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
b4c0: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
b4d0: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
b4e0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
b4f0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
b500: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
b510: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
b520: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
b530: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
b540: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
b550: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
b560: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b570: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
b580: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
b590: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
b5a0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b5b0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b5c0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
b5d0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b5e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
b5f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
b600: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
b610: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
b620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
b630: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
b640: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
b650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
b660: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
b670: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
b680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
b690: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
b6a0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
b6b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b6c0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
b6d0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
b6e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
b6f0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
b700: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
b710: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
b720: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
b730: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b740: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
b750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
b760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b770: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
b780: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
b790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7a0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
b7b0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
b7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b7d0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
b7e0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
b7f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b800: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
b810: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
b820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b830: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
b840: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
b850: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b860: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
b870: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
b880: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b890: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
b8a0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
b8b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
b8c0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
b8d0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
b8e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b8f0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
b900: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
b910: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b920: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
b930: 20 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43 41      22../*.** CA
b940: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
b950: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
b960: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
b970: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
b980: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
b990: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
b9a0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
b9b0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
b9c0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
b9d0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
b9e0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
b9f0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
ba00: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
ba10: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
ba20: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
ba30: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
ba40: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
ba50: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
ba60: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
ba70: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
ba80: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
ba90: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
baa0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
bab0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
bac0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bad0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
bae0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
baf0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
bb00: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
bb10: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
bb20: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
bb30: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
bb40: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
bb50: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
bb60: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
bb70: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
bb80: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
bb90: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
bba0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
bbb0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
bbc0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
bbd0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
bbe0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
bbf0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
bc00: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
bc10: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
bc20: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
bc30: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
bc40: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
bc50: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
bc60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
bc70: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
bc80: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
bc90: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
bca0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
bcb0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
bcc0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
bcd0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bce0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
bcf0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
bd00: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
bd10: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
bd20: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
bd30: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
bd40: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
bd50: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
bd60: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
bd70: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
bd80: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
bd90: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
bda0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
bdb0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
bdc0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
bdd0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
bde0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
bdf0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
be00: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
be10: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
be20: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
be30: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
be40: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
be50: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
be60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
be70: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
be80: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
be90: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
bea0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
beb0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
bec0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
bed0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
bee0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
bef0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
bf00: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
bf10: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
bf20: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
bf30: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
bf40: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
bf50: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
bf60: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
bf70: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
bf80: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
bf90: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
bfa0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
bfb0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
bfc0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
bfd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
bfe0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
bff0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c000: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c010: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c020: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c030: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c040: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c050: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c060: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c070: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c080: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c090: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c0a0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c0b0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c0c0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c0d0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c0e0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c0f0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c100: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c110: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c120: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c130: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c160: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c170: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c180: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c190: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c1a0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c1b0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c1c0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c1d0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c1e0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c1f0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c200: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c210: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c220: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c230: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c240: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c250: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c260: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c270: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c280: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c290: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c2a0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c2b0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c2c0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c2d0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c2e0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c2f0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c300: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c310: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c330: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c340: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c350: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c360: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c370: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c380: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c390: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c3a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c3b0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c3c0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c3d0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c3e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
c3f0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
c400: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c410: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
c420: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
c430: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
c440: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
c450: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
c460: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c470: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
c480: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c490: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
c4a0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
c4b0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
c4c0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
c4d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c4e0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
c4f0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
c500: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
c510: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
c520: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
c530: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
c540: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
c550: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
c560: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
c570: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
c580: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
c590: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
c5a0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
c5b0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
c5c0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
c5d0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
c5e0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
c5f0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
c600: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
c610: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
c620: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
c630: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
c640: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
c650: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
c660: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
c670: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c680: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c690: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
c6a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c6b0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
c6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c6d0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
c6e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c6f0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
c700: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c710: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
c720: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c730: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
c740: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c750: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
c760: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
c770: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c780: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
c790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
c7a0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
c7b0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
c7c0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
c7d0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
c7e0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
c7f0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
c800: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
c810: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
c820: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
c830: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
c840: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
c850: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
c860: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
c870: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
c880: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
c890: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
c8a0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
c8b0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
c8c0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
c8d0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
c8e0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
c8f0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
c900: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
c910: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
c920: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
c930: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
c940: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
c950: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
c960: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
c970: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
c980: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
c990: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
c9a0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
c9b0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
c9c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
c9d0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
c9e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
c9f0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ca00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
ca10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
ca20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ca30: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
ca40: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
ca50: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ca60: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
ca70: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
ca80: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
ca90: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
caa0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
cab0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cac0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
cad0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
cae0: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
caf0: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
cb00: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
cb10: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
cb20: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
cb30: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
cb40: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
cb50: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
cb60: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
cb70: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
cb80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
cb90: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
cba0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
cbb0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
cbc0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
cbd0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
cbe0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
cbf0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
cc00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc10: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
cc20: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
cc30: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
cc40: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
cc50: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
cc60: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
cc70: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
cc80: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
cc90: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
cca0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
ccb0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
ccc0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
ccd0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
cce0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
ccf0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
cd00: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
cd10: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
cd20: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
cd30: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
cd40: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
cd50: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
cd60: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
cd70: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
cd80: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
cd90: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
cda0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
cdb0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
cdc0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
cdd0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
cde0: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
cdf0: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
ce00: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
ce10: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
ce20: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
ce30: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
ce40: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
ce50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ce60: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
ce70: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
ce80: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
ce90: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
cea0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
ceb0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
cec0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
ced0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
cee0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
cef0: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
cf00: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
cf10: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
cf20: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
cf30: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
cf40: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
cf50: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
cf60: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
cf70: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
cf80: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
cf90: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
cfa0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
cfb0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
cfc0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
cfd0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
cfe0: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
cff0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d000: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d010: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d020: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d030: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d040: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d050: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d060: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d070: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d080: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d090: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d0a0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d0b0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d0c0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d0d0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d0e0: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d0f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d100: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d110: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d120: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d130: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d140: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d150: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d160: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d170: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d180: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d190: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d1a0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d1b0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d1c0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d1d0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d1e0: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d1f0: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d200: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d210: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d220: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d230: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d240: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d250: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d260: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d270: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d280: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d290: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d2a0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d2b0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d2c0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d2d0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d2e0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d2f0: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d300: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d310: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d320: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d330: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d340: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d350: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d360: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d370: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d380: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d390: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d3a0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d3b0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d3c0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d3d0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d3e0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
d3f0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
d400: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
d410: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
d420: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
d430: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
d440: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
d450: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
d460: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
d470: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
d480: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
d490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d4a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
d4b0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
d4c0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
d4d0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
d4e0: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
d4f0: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
d500: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
d510: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
d520: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
d530: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
d540: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d550: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
d560: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
d570: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
d580: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
d590: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
d5a0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
d5b0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
d5c0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
d5d0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d5e0: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
d5f0: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
d600: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
d610: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d620: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
d630: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
d640: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
d650: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
d660: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
d670: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
d680: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
d690: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
d6a0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
d6b0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
d6c0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
d6d0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
d6e0: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
d6f0: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
d700: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
d710: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
d720: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
d730: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
d740: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
d750: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
d760: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
d770: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
d780: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
d790: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
d7a0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
d7b0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
d7c0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
d7d0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
d7e0: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
d7f0: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
d800: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
d810: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
d820: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
d830: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
d840: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
d850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
d860: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d870: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
d880: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
d890: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
d8a0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
d8b0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
d8c0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
d8d0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
d8e0: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
d8f0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
d900: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
d910: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
d920: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
d930: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
d940: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
d950: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
d960: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d970: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
d980: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
d990: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
d9a0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
d9b0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
d9c0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
d9d0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
d9e0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
d9f0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
da00: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
da10: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
da20: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
da30: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
da40: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
da50: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
da60: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
da70: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
da80: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
da90: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
daa0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
dab0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
dac0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
dad0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
dae0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
daf0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
db00: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
db10: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
db20: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
db30: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
db40: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
db50: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
db60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
db70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
db80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
db90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
dba0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
dbb0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
dbc0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
dbd0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dbe0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dbf0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
dc00: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
dc10: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dc20: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dc30: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
dc40: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
dc50: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
dc60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
dc80: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
dc90: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
dca0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
dcb0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dcc0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
dcd0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
dce0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dcf0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
dd00: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
dd10: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
dd20: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
dd30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
dd40: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
dd50: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
dd60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
dd70: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
dd80: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
dd90: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
dda0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ddb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ddc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ddd0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
dde0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ddf0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
de00: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
de10: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
de20: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
de30: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
de40: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
de50: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
de60: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
de70: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
de80: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
de90: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
dea0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
deb0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
dec0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ded0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
dee0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
def0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
df00: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df30: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
df40: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
df50: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
df60: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
df70: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
df80: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
df90: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
dfa0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
dfb0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dfc0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dfd0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
dfe0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
dff0: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e000: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e020: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e030: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e040: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e050: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e060: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e070: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e080: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e090: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e0a0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e0b0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e0c0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e0d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e0e0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e0f0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e100: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e110: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e120: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e130: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e140: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e150: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e160: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e170: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e180: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e190: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e1a0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e1b0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e1c0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e1d0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e1e0: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e1f0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e200: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e210: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e220: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e230: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e240: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e250: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e260: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e270: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e280: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e290: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e2a0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e2b0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e2c0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e2d0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e2e0: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e2f0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e300: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e310: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e320: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e330: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e340: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e350: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e360: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e370: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e380: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e390: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e3a0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e3b0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e3c0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e3d0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e3e0: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
e3f0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e400: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e410: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
e420: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e430: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e440: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
e450: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
e460: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e470: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
e480: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
e490: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
e4a0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
e4b0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
e4c0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
e4d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e4e0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
e4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e500: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e510: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
e520: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
e530: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
e540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e550: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
e560: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
e570: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e580: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
e590: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
e5a0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e5b0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e5c0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
e5d0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
e5e0: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
e5f0: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
e600: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
e610: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
e620: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
e630: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
e640: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
e650: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
e660: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
e670: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
e680: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
e690: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e6a0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e6b0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e6c0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
e6d0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e6e0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e6f0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e700: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e710: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e720: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e730: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e740: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
e750: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
e760: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
e770: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
e780: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
e790: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
e7a0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
e7b0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
e7c0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e7d0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
e7e0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
e7f0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
e800: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
e810: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
e820: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
e830: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
e840: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
e850: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
e860: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e870: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
e880: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
e890: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
e8a0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
e8b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
e8c0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
e8d0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
e8e0: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
e8f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
e900: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
e910: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
e920: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
e930: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e940: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
e950: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
e960: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
e970: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
e980: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
e990: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
e9a0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
e9b0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
e9c0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
e9d0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
e9e0: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
e9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ea00: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
ea10: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
ea20: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
ea30: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ea40: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
ea50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ea60: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
ea70: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
ea80: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ea90: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
eaa0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
eab0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
eac0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
ead0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
eae0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
eaf0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
eb00: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
eb10: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
eb20: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
eb30: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
eb40: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
eb50: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
eb60: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
eb70: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
eb80: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
eb90: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
eba0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ebb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
ebc0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ebd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ebe0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
ebf0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ec00: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
ec10: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ec20: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ec30: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
ec40: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
ec50: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
ec60: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
ec70: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
ec80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ec90: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
eca0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
ecb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ecc0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
ecd0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
ece0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
ecf0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
ed00: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
ed10: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
ed20: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
ed30: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
ed40: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ed50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ed60: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ed70: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
ed80: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
ed90: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
eda0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
edb0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
edc0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
edd0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
ede0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
edf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ee00: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
ee10: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
ee20: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
ee30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
ee40: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
ee50: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
ee60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
ee70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
ee90: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
eea0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
eeb0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
eec0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
eed0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
eee0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
eef0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
ef00: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
ef10: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
ef20: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
ef30: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
ef40: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
ef50: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
ef60: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
ef70: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
ef80: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
ef90: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
efa0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
efb0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
efc0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
efd0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
efe0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
eff0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f000: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f010: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f020: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f030: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f040: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f050: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f060: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f070: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f080: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f090: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f0a0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f0b0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f0c0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f0d0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f0e0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f0f0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f100: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f110: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f120: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f130: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f140: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f150: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f160: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f170: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f180: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f190: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f1a0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f1b0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f1c0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f1d0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f1e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f1f0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f200: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f210: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f220: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f230: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f240: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f250: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f260: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f270: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f280: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f290: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f2a0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f2b0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f2c0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f2d0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f2e0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f2f0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f300: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f310: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f320: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f330: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f340: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f350: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f360: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f370: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f380: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f390: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f3a0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f3b0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f3c0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f3d0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f3e0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
f3f0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
f400: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
f410: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f420: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
f430: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f440: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f450: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
f460: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
f470: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
f480: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
f490: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
f4a0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
f4b0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
f4c0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f4d0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
f4e0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
f4f0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
f500: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
f510: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
f520: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f540: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
f550: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
f560: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f570: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
f580: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
f590: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
f5a0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f5b0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
f5c0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
f5d0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f5e0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
f5f0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
f600: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
f610: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
f620: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
f630: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
f640: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
f650: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f660: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
f670: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
f680: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
f690: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
f6a0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
f6b0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
f6c0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
f6d0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f6e0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
f6f0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f700: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
f710: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
f720: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
f730: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
f740: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
f750: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f760: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
f770: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f780: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
f790: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
f7a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f7b0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
f7c0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
f7d0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
f7e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f7f0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
f800: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
f810: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
f820: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
f830: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
f840: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
f850: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
f860: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
f870: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
f880: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
f890: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
f8a0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
f8b0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
f8c0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
f8d0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
f8e0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
f8f0: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
f900: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
f910: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
f920: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
f930: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
f940: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
f950: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f960: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
f970: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
f980: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
f990: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
f9a0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
f9b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
f9c0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f9d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f9e0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
f9f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
fa00: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
fa10: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
fa20: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
fa30: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
fa40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fa60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
fa70: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fa80: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
fa90: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
faa0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
fab0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fac0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
fad0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
fae0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
faf0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fb00: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
fb10: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
fb20: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fb30: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fb40: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
fb50: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
fb60: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
fb70: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
fb80: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
fb90: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
fba0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
fbb0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
fbc0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
fbd0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
fbe0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
fbf0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
fc00: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
fc10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
fc20: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
fc30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fc40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fc50: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
fc60: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
fc70: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
fc80: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
fc90: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
fca0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
fcb0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
fcc0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
fcd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fce0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
fcf0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
fd00: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
fd10: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
fd20: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
fd30: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
fd40: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
fd50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fd60: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
fd70: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
fd80: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
fd90: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
fda0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
fdb0: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
fdc0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
fdd0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
fde0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
fdf0: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
fe00: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
fe10: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
fe20: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
fe40: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
fe50: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
fe60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
fe70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
fe80: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
fe90: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
fea0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
feb0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
fec0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
fed0: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
fee0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
fef0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
ff00: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
ff10: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
ff20: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
ff30: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
ff40: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
ff50: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
ff60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ff70: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
ff80: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
ff90: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
ffa0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ffb0: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ffc0: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ffd0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ffe0: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
fff0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10000 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10010 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10020 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10030 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10040 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
10050 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
10060 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
10070 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
10080 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10090 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
100a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
100b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
100c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
100d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
100e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
100f0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
10100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10110 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
10120 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10130 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10140 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
10150 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
10160 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
10170 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
10180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
10190 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
101a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
101b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
101c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
101d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
101e0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
101f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10200 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10210 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10220 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10230 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10240 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
10250 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
10260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10270 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
10280 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
10290 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
102a0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
102b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
102c0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
102d0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
102e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
102f0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10300 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10310 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10320 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10330 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10340 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
10350 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
10360 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10370 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
10380 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
10390 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
103a0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
103b0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
103c0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
103d0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
103e0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
103f0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10400 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10410 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10420 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10430 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10440 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
10450 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
10460 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10470 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
10480 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
10490 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
104a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
104b0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
104c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
104d0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
104e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
104f0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
10500 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
10510 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10520 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10530 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10540 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
10550 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
10560 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
10570 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
10580 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
10590 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
105a0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
105b0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
105c0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
105d0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
105e0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
105f0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
10600 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
10610 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
10620 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10640 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
10650 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
10660 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
10670 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
10680 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
10690 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
106a0 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
106b0 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
106c0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
106d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
106e0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
106f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10700 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
10710 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
10720 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10730 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10740 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
10750 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10760 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10770 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
10780 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
10790 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
107a0 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
107b0 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
107c0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
107d0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
107e0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
107f0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
10800 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
10810 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
10820 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10830 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10840 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10850 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10860 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10870 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10880 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10890 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
108a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
108b0 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
108c0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
108d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
108e0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
108f0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10900 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10910 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10920 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
10940 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
10950 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
10960 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
10970 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10980 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
10990 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
109a0 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
109b0 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
109c0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
109d0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
109e0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
109f0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
10a00 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
10a10 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10a20 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
10a30 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
10a40 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
10a50 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10a60 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
10a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
10a80 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
10a90 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
10aa0 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
10ab0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10ac0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
10ad0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
10ae0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
10af0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
10b00 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
10b10 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
10b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10b30 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10b40 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
10b50 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
10b60 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
10b70 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
10b80 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
10b90 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
10ba0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
10bb0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
10bc0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
10bd0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10be0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10bf0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
10c00 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
10c10 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
10c20 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
10c30 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
10c40 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
10c50 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
10c60 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
10c70 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
10c80 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
10c90 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10ca0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10cb0 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10cc0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10cd0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10ce0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10cf0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10d00 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10d10 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10d20 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10d30 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10d40 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10d50 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
10d60 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
10d70 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10d80 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
10d90 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10da0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
10db0 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
10dc0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
10dd0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
10de0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10df0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
10e00 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
10e10 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
10e20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
10e30 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
10e40 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
10e50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
10e60 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
10e70 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
10e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
10e90 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
10ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10eb0 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
10ec0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
10ed0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
10ee0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
10ef0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
10f00 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
10f10 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
10f20 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10f30 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
10f40 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
10f50 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
10f60 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
10f70 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
10f80 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
10f90 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
10fa0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
10fb0 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
10fc0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
10fd0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
10fe0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
10ff0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11000 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11010 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11020 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11030 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11040 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11050 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11060 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11070 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11080 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11090 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
110a0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
110b0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
110c0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
110d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
110e0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
110f0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
11100 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
11110 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11120 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11130 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11140 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
11150 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
11160 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
11170 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
11180 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
11190 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
111a0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
111b0 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
111c0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
111d0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
111e0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
111f0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11200 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
11210 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
11220 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11230 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11240 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
11250 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11260 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
11270 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
11280 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
11290 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
112a0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
112b0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
112c0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
112d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
112e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
112f0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
11300 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
11310 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11320 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11330 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11340 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11350 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11360 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11370 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11390 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
113a0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
113b0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
113c0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
113d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
113e0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
113f0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11400 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11410 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11420 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11430 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11440 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
11450 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
11460 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
11470 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11480 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11490 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
114a0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
114b0 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
114c0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
114d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
114e0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
114f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11500 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11510 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
11520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11530 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11550 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11560 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11570 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11580 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11590 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
115a0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
115b0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
115c0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
115d0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
115e0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
115f0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
11600 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
11610 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
11620 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11630 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11640 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11650 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11660 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11670 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11680 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11690 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
116a0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
116b0 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
116c0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
116d0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
116e0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
116f0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
11700 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11710 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
11720 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11730 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11750 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
11760 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11770 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11790 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
117a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
117b0 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
117c0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
117d0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
117e0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
117f0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11800 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11810 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
11820 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11830 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11840 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11850 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11860 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11870 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11880 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
118a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
118b0 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
118c0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
118d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
118e0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
118f0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11900 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11910 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11920 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11930 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
11940 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
11950 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
11960 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
11970 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
11980 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
11990 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
119a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
119b0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
119c0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
119d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
119e0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
119f0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11a00 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11a10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11a20 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11a30 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11a40 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
11a50 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
11a60 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11a70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11a80 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
11a90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11aa0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
11ab0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
11ac0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
11ad0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11ae0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11b00 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
11b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11b20 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
11b30 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11b40 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11b50 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11b60 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11b70 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11b80 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
11b90 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
11ba0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
11bb0 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
11bc0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
11bd0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
11be0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
11bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11c00 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11c10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11c20 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
11c30 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
11c40 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
11c50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11c60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
11c70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
11c80 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
11c90 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11ca0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11cb0 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11cd0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11ce0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11cf0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11d00 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11d10 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11d30 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
11d40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
11d50 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
11d60 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
11d70 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
11d80 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11da0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11db0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11dc0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11dd0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11de0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11df0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11e00 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
11e10 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
11e20 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11e30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11e40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11e50 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11e60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
11e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11e80 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
11e90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11ea0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11eb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11ec0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ed0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
11ee0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11ef0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11f00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11f10 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11f20 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11f30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
11f40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11f50 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11f60 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
11f70 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
11f80 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
11f90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11fa0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
11fb0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
11fc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11fd0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
11fe0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11ff0 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12000 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12010 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12020 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12030 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12040 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12050 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12060 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12070 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12080 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12090 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
120a0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
120b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
120c0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
120d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
120e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
120f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12110 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12130 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12140 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
12150 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
12160 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
12170 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
12180 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
12190 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
121a0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
121b0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
121c0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
121d0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
121e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121f0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12200 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12210 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12230 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12240 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
12250 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
12260 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12280 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
12290 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
122a0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
122b0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
122c0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
122d0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
122e0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
122f0 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
12300 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12310 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12320 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
12330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
12340 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
12350 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
12360 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12370 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
12380 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
12390 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
123a0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
123b0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
123c0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
123d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
123e0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
123f0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12400 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12410 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12420 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12430 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12440 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12450 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
12460 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
12470 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12480 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12490 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
124a0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
124b0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
124c0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
124d0 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
124e0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
124f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12500 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12510 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12520 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12540 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
12550 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12560 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
12570 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
12580 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
12590 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
125a0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
125b0 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
125c0 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
125d0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
125e0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
125f0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12600 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12610 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12620 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12630 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12640 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12650 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12660 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12670 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12680 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12690 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
126a0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
126b0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
126c0 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
126d0 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
126e0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
126f0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12700 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12710 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12720 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12730 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12740 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12750 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
12760 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
12770 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
12780 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
12790 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
127a0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
127b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
127c0 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
127d0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
127e0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
127f0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12800 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12810 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12820 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
12830 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12840 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12860 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12870 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12880 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12890 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
128a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
128b0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
128c0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
128d0 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
128e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
128f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12900 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12910 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
12920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12930 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12940 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12950 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12960 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12970 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
12980 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
12990 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
129a0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
129b0 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
129c0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
129d0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
129e0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
129f0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
12a00 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12a10 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
12a20 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
12a30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12a40 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
12a50 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12a60 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12a70 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
12a80 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
12a90 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
12aa0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12ab0 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
12ac0 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
12ad0 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
12ae0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
12af0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
12b00 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
12b10 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
12b20 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
12b30 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
12b40 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
12b50 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
12b60 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12b70 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
12b80 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
12b90 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
12ba0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
12bb0 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
12bc0 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
12bd0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
12be0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
12bf0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
12c00 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
12c10 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
12c20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
12c30 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
12c40 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
12c50 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12c60 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12c70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12c80 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
12c90 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
12ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12cb0 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
12cc0 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
12cd0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
12ce0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
12cf0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
12d00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
12d10 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12d20 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
12d30 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12d40 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
12d50 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
12d60 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
12d70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
12d80 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
12d90 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
12da0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
12db0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12dc0 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
12dd0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
12de0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
12df0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
12e00 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
12e10 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
12e20 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
12e30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
12e40 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
12e50 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
12e60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12e70 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12e80 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12e90 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12ea0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
12eb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
12ec0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
12ed0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
12ee0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
12ef0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
12f00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12f10 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
12f20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12f30 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
12f40 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12f50 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
12f60 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
12f70 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
12f80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
12f90 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
12fa0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
12fb0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
12fc0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
12fd0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
12fe0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
12ff0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
13000 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
13010 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
13020 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
13030 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
13040 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
13050 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
13060 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
13070 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
13080 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
13090 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
130a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
130b0 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
130c0 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
130d0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
130e0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
130f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13100 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
13110 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
13120 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13130 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13140 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13150 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13160 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13170 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13180 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13190 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
131a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
131b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
131c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
131d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
131e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
131f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13200 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13220 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13230 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13240 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13250 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13260 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13270 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13280 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
132a0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
132b0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
132c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
132d0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
132e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
132f0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13300 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13310 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13320 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13330 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13340 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13350 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13360 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13370 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13380 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13390 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
133a0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
133b0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
133c0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
133d0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
133e0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
133f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13400 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13410 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13430 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13440 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13450 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13460 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13470 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13480 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
134a0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
134b0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
134c0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
134d0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
134e0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
134f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13500 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13510 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13520 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13530 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13540 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13550 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13570 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
13580 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13590 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
135a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
135b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
135c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
135d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
135e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
135f0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13600 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13610 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13620 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13630 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
13640 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13650 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13660 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13670 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
13680 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13690 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
136a0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
136b0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
136c0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
136d0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
136e0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
136f0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
13700 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
13710 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
13720 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
13730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
137a0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
137b0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
137c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
137d0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
137e0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
137f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13800 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13810 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
13820 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13830 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13850 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13870 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
13880 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13890 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
138a0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
138b0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
138c0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
138d0 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
138e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
138f0 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
13900 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13910 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
13920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13930 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
13940 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
13950 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13960 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13970 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
13980 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
13990 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
139a0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
139b0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
139c0 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139e0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
139f0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
13a00 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
13a10 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13a20 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
13a30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13a40 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13a50 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13a60 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13a80 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13a90 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13aa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ab0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13ac0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ad0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13ae0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13af0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13b00 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13b10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13b20 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
13b30 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13b40 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
13b50 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
13b60 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
13b70 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
13b80 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13b90 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
13ba0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13bb0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
13bc0 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
13bd0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13be0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
13bf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13c00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13c10 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13c30 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
13c40 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13c50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13c60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13c70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
13c90 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13ca0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
13cb0 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
13cc0 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
13cd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13ce0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
13cf0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
13d00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d10 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
13d20 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
13d30 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
13d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13d50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13d60 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
13d70 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
13d80 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
13d90 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
13da0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
13db0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
13dc0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
13dd0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
13de0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
13df0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
13e00 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
13e10 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
13e20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
13e30 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
13e40 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
13e50 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
13e60 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
13e70 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
13e80 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
13e90 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
13ea0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
13eb0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
13ec0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
13ed0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
13ee0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
13ef0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
13f00 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
13f10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13f20 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
13f30 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
13f40 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
13f50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13f60 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
13f70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
13f80 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
13f90 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
13fa0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
13fb0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
13fc0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
13fd0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
13fe0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
13ff0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
14000 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
14010 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
14020 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
14030 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
14040 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
14050 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
14060 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
14070 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
14080 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14090 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
140a0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
140b0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
140c0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
140d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
140e0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
140f0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
14100 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
14110 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
14120 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
14130 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
14140 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
14150 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
14160 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
14170 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
14180 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
14190 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
141a0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
141b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
141c0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
141d0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
141e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
141f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14200 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
14210 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
14220 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14230 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14240 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
14250 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
14260 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14270 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
14280 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
14290 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
142a0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
142b0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
142c0 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
142d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
142e0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
142f0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
14300 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
14310 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14320 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
14330 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14340 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14350 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14360 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14370 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14380 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14390 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
143a0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
143b0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
143c0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
143d0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
143e0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
143f0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14400 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14410 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14420 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14430 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14440 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14450 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14460 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14470 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14480 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14490 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
144a0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
144b0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
144c0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
144d0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
144e0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
144f0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14500 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14510 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14520 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14530 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14540 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14550 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14560 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14570 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14580 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
14590 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
145a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
145b0 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
145c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
145d0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
145e0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
145f0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
14600 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14610 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14620 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20  ptimizer.  ^The 
14630 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14640 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
14650 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
14660 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
14670 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
14680 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
14690 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
146a0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
146b0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
146c0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
146d0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
146e0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
146f0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14700 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14710 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14720 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14730 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14740 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
14750 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
14760 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
14770 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
14780 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14790 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
147a0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
147b0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
147c0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
147d0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
147e0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
147f0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14800 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14810 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14820 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14830 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14850 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14870 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14880 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14890 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
148a0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
148b0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
148c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
148d0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
148e0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
148f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14900 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14910 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14920 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14940 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14950 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14960 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14970 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14980 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14990 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
149a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
149b0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
149c0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
149d0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
149e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
149f0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14a00 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14a10 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14a20 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14a30 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14a40 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14a50 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14a60 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14a70 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14a80 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14a90 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14aa0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14ab0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14ac0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14ad0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14ae0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14af0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14b00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14b10 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14b30 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
14b40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14b50 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
14b60 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
14b70 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
14b80 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
14b90 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
14ba0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
14bb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
14bc0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
14bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
14be0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
14bf0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
14c00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
14c10 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
14c20 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
14c30 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
14c40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14c50 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
14c60 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
14c70 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
14c80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14c90 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
14ca0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
14cb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
14cc0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
14cd0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
14ce0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
14cf0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
14d00 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
14d10 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
14d20 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
14d30 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
14d40 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
14d50 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
14d60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14d80 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
14d90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14da0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
14db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14dc0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
14dd0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
14de0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
14df0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
14e00 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
14e10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
14e20 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
14e30 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
14e40 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
14e50 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
14e60 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
14e70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
14e80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14e90 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
14ea0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
14eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
14ec0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
14ed0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
14ee0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
14ef0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
14f00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
14f10 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
14f20 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
14f30 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14f40 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
14f50 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
14f60 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
14f70 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
14f80 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
14f90 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
14fa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
14fb0 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
14fc0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
14fd0 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
14fe0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
14ff0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15000 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15010 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15020 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15030 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15040 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15050 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15060 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
15070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15080 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15090 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
150a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
150b0 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
150c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
150d0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
150e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
150f0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a  ed for Windows.*
15100 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
15110 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15120 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15130 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  acro defined..**
15140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
15150 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
15160 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
15170 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
15180 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
15190 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
151a0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
151b0 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c  eated heap..** <
151c0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dl>.**.** [[SQL
151d0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 4f 52 4b 45  ITE_CONFIG_WORKE
151e0 52 5f 54 48 52 45 41 44 53 5d 5d 0a 2a 2a 20 3c  R_THREADS]].** <
151f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15200 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 0a  _WORKER_THREADS.
15210 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
15220 4f 4e 46 49 47 5f 57 4f 52 4b 45 52 5f 54 48 52  ONFIG_WORKER_THR
15230 45 41 44 53 20 74 61 6b 65 73 20 61 20 73 69 6e  EADS takes a sin
15240 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
15250 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 74 20  type int..** It 
15260 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 74  is used to set t
15270 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 61 63  he number of bac
15280 6b 67 72 6f 75 6e 64 20 77 6f 72 6b 65 72 20 74  kground worker t
15290 68 72 65 61 64 73 20 74 68 61 74 20 6d 61 79 20  hreads that may 
152a0 62 65 0a 2a 2a 20 6c 61 75 6e 63 68 65 64 20 77  be.** launched w
152b0 68 65 6e 20 73 6f 72 74 69 6e 67 20 6c 61 72 67  hen sorting larg
152c0 65 20 61 6d 6f 75 6e 74 73 20 6f 66 20 64 61 74  e amounts of dat
152d0 61 2e 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  a. A value of 0 
152e0 6d 65 61 6e 73 20 6c 61 75 6e 63 68 20 0a 2a 2a  means launch .**
152f0 20 6e 6f 20 62 61 63 6b 67 72 6f 75 6e 64 20 74   no background t
15300 68 72 65 61 64 73 20 61 74 20 61 6c 6c 2e 20 54  hreads at all. T
15310 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
15320 72 20 6f 66 20 62 61 63 6b 67 72 6f 75 6e 64 20  r of background 
15330 74 68 72 65 61 64 73 20 0a 2a 2a 20 61 6c 6c 6f  threads .** allo
15340 77 65 64 20 69 73 20 63 6f 6e 66 69 67 75 72 65  wed is configure
15350 64 20 61 74 20 62 75 69 6c 64 2d 74 69 6d 65 20  d at build-time 
15360 62 79 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 41  by the SQLITE_MA
15370 58 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  X_WORKER_THREADS
15380 20 0a 2a 2a 20 70 72 65 2d 70 72 6f 63 65 73 73   .** pre-process
15390 6f 72 20 6f 70 74 69 6f 6e 2e 20 0a 2a 2a 20 3c  or option. .** <
153a0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
153c0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
153d0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
153e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
153f0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15400 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15410 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15420 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
15430 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15440 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15450 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
15460 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15470 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15490 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
154a0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
154b0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
154c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
154d0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
154e0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
154f0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15510 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15520 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
15530 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15550 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
15560 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
15570 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
15580 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
15590 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
155a0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
155b0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
155c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
155d0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
155e0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
155f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15600 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15610 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15620 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
15630 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15640 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
15650 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
15660 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
15670 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
15680 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
15690 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
156a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
156b0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
156c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
156d0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
156e0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
156f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15700 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15710 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15720 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15730 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
15740 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
15750 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
15760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15770 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
15780 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
15790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
157a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
157b0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
157c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
157d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
157e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
157f0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15800 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15810 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15820 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15830 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15840 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
15850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15860 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15870 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
15880 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
15890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
158a0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
158b0 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
158c0 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
158d0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
158e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
158f0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15900 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15910 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
15920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 4f  SQLITE_CONFIG_WO
15930 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
15940 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 6e 57 6f    24  /* int nWo
15950 72 6b 65 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rker */../*.** C
15960 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
15970 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
15980 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
15990 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
159a0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
159b0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
159c0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
159d0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
159e0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
159f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15a00 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
15a10 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15a20 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
15a30 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
15a40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
15a50 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15a60 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
15a70 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
15a80 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
15a90 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
15aa0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
15ab0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
15ac0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
15ad0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
15ae0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
15af0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
15b00 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
15b10 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
15b20 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
15b30 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15b40 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15b50 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15b60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15b70 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15b80 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15b90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15ba0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15bb0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
15bc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
15bd0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
15be0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
15bf0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
15c00 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
15c10 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15c20 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
15c30 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
15c40 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
15c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15c60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
15c70 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
15c80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15c90 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
15ca0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15cb0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15cc0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15cd0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
15ce0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
15cf0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
15d00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
15d10 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
15d20 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15d30 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
15d40 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
15d50 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
15d60 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
15d70 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
15d80 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
15d90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15da0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
15db0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15dc0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15dd0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15de0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
15df0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15e00 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
15e10 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
15e20 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
15e30 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
15e40 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
15e50 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
15e60 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
15e70 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
15e80 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15e90 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
15ea0 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
15eb0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
15ec0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
15ed0 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
15ee0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15ef0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
15f00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
15f10 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
15f20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
15f30 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
15f40 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
15f50 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
15f60 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
15f70 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15f80 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
15f90 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
15fa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
15fb0 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
15fc0 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
15fd0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
15fe0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
15ff0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16000 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
16010 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
16020 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
16030 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
16040 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
16050 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
16060 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
16070 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
16080 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
16090 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
160a0 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
160b0 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
160c0 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
160d0 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
160e0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
160f0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
16100 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
16110 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
16120 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
16130 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16140 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
16150 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16160 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
16170 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16180 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
16190 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
161a0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
161b0 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
161c0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
161d0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
161e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
161f0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16200 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16210 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
16220 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
16230 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
16240 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
16250 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16260 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16270 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
16280 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16290 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
162a0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
162b0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
162c0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
162d0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
162e0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
162f0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
16300 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
16310 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
16320 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
16330 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
16340 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
16350 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
16360 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
16370 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16380 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16390 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
163a0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
163b0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
163c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
163d0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
163e0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
163f0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
16400 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
16410 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16420 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16430 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16440 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16450 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16460 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16470 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
16480 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16490 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
164a0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
164b0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
164c0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
164d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
164e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
164f0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16500 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16510 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16520 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
16530 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
16540 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
16550 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
16560 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
16570 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
16580 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
16590 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
165a0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
165b0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
165c0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
165d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
165e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
165f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16600 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
16610 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
16620 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16630 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16640 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
16650 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
16660 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16670 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16680 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
16690 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
166a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
166b0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
166c0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
166d0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
166e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
166f0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16700 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
16710 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16720 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
16730 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
16740 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
16750 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
16760 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
16770 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
16780 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
16790 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
167a0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
167b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
167c0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
167d0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
167e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
167f0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
16800 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
16810 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
16820 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
16830 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
16840 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
16850 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
16860 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
16870 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
16880 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
16890 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
168a0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
168b0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
168c0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
168d0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
168e0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
168f0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
16900 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
16910 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
16920 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
16930 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
16940 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
16950 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
16960 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
16970 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
16980 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
16990 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
169a0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
169b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
169c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
169d0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
169e0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
169f0 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
16a00 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
16a10 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
16a20 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
16a30 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
16a40 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
16a50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
16a60 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
16a70 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
16a80 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
16a90 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
16aa0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
16ab0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
16ac0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
16ad0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
16ae0 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
16af0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
16b00 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
16b10 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16b20 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
16b30 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
16b40 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
16b50 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
16b60 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
16b70 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16b80 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
16b90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
16ba0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
16bb0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
16bc0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
16bd0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
16be0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
16bf0 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
16c00 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
16c10 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
16c20 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16c30 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
16c40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16c50 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
16c60 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
16c70 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
16c80 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
16c90 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
16ca0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
16cb0 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
16cc0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
16cd0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
16ce0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
16cf0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
16d00 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
16d10 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
16d20 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
16d30 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
16d40 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
16d50 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
16d60 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
16d70 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
16d80 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
16d90 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
16da0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
16db0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
16dc0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
16dd0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
16de0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
16df0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
16e00 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
16e10 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
16e20 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
16e30 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
16e40 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
16e50 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
16e60 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
16e70 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
16e80 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
16e90 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
16ea0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
16eb0 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
16ec0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
16ed0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
16ee0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
16ef0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
16f00 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
16f10 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
16f20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
16f30 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
16f40 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
16f50 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
16f60 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
16f70 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
16f80 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
16f90 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
16fa0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
16fb0 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
16fc0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
16fd0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
16fe0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
16ff0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
17000 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
17010 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
17020 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
17030 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
17040 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17050 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
17060 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
17070 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
17080 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
17090 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
170a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
170b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
170c0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
170d0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
170e0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
170f0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
17100 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
17110 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
17120 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17140 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17150 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
17160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17170 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
17180 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
17190 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
171a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
171b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
171c0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
171d0 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
171e0 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
171f0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
17200 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
17210 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17220 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17240 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
17250 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
17260 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
17270 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
17280 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
17290 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
172a0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
172b0 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
172c0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
172d0 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
172e0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
172f0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
17300 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
17310 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17320 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17330 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17340 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17350 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
17360 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
17370 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
17380 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
17390 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
173a0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
173b0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
173c0 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
173d0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
173e0 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
173f0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17400 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
17410 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17420 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17430 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17440 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
17450 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
17460 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
17470 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
17480 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
17490 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
174a0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
174b0 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
174c0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
174d0 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
174e0 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
174f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
17500 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
17510 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17520 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17530 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17540 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
17550 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
17560 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
17570 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
17580 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
17590 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
175a0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
175b0 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
175c0 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
175d0 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
175e0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
175f0 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
17600 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17610 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17620 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17630 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17640 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
17650 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17660 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
17670 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
17680 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
17690 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
176a0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
176b0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
176c0 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
176d0 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
176e0 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
176f0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
17700 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
17710 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17720 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17740 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
17750 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
17760 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
17770 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
17780 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
177a0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
177b0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
177c0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
177d0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
177e0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
177f0 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
17800 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
17810 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17820 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17830 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17840 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17850 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17860 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
17870 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17880 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17890 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
178a0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
178b0 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
178c0 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
178d0 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
178e0 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
178f0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
17900 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
17910 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17920 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17930 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17940 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17950 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17960 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17970 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17980 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
17990 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
179a0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
179b0 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
179c0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
179d0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
179e0 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
179f0 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
17a00 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
17a10 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17a20 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17a30 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17a40 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17a50 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17a60 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17a70 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17a80 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17a90 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17aa0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17ab0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17ac0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17ad0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17ae0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17af0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17b00 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17b10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17b20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17b30 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17b40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17b50 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17b60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17b70 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17b80 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17b90 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17ba0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17bb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
17bc0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
17bd0 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
17be0 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
17bf0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
17c00 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
17c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17c20 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
17c30 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
17c40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17c50 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
17c60 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
17c70 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
17c80 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17c90 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
17ca0 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
17cb0 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
17cc0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17cd0 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
17ce0 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
17cf0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17d00 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
17d10 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
17d20 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
17d30 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
17d40 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
17d50 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
17d60 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
17d70 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
17d80 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
17d90 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
17da0 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
17db0 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
17dc0 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
17dd0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
17de0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
17df0 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
17e00 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
17e10 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
17e20 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
17e30 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17e40 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
17e50 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
17e60 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
17e70 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
17e80 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
17e90 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
17ea0 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
17eb0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
17ec0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
17ed0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17ee0 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
17ef0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
17f00 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
17f10 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17f20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17f30 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17f40 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
17f50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17f60 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17f70 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
17f80 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
17f90 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
17fa0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
17fb0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17fc0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
17fd0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
17fe0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
17ff0 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
18000 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
18010 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
18020 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18030 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18050 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
18060 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
18070 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
18080 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
18090 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
180a0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
180b0 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
180c0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
180d0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
180e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
180f0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
18100 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
18110 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
18120 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
18130 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
18140 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
18150 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
18160 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
18170 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
18180 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
18190 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
181a0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
181b0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
181c0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
181d0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
181e0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
181f0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
18200 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
18210 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
18220 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18230 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18240 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18250 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
18260 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
18270 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
18280 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18290 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
182a0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
182b0 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
182c0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
182d0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
182e0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
182f0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
18300 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
18310 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
18320 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
18330 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
18340 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
18350 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
18360 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
18370 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
18380 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
18390 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
183a0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
183b0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
183c0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
183d0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
183e0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
183f0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
18400 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
18410 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
18420 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
18430 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
18440 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
18450 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
18460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18470 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
18480 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
18490 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
184a0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
184b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
184c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
184d0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
184e0 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
184f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18500 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18510 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18520 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18530 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
18540 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
18550 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
18560 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
18570 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
18580 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
18590 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
185a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
185b0 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
185c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
185d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
185e0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
185f0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
18600 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
18610 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
18620 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
18630 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18640 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
18650 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18660 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
18670 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
18680 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
18690 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
186a0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
186b0 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
186c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
186d0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
186e0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
186f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18700 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
18710 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
18730 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
18740 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
18750 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
18760 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
18770 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
18780 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
18790 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
187a0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
187b0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
187c0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
187d0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
187e0 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
187f0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
18800 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
18810 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
18820 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
18830 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
18840 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
18850 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
18860 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18870 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
18880 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
18890 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
188a0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
188b0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
188c0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
188d0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
188e0 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
188f0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
18900 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
18910 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18920 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
18930 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
18940 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
18950 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
18960 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
18970 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
18980 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
18990 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
189a0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
189b0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
189c0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
189d0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
189e0 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
189f0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
18a00 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
18a10 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
18a20 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
18a30 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
18a40 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
18a50 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
18a60 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
18a70 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
18a80 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
18a90 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
18aa0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
18ab0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
18ac0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
18ad0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
18ae0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
18af0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
18b00 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
18b10 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
18b20 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
18b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18b40 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
18b50 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
18b60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
18b70 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
18b80 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
18b90 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
18ba0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
18bb0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
18bc0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
18bd0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
18be0 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
18bf0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
18c00 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
18c10 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
18c20 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
18c30 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18c40 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
18c50 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
18c60 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
18c70 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
18c80 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18c90 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
18ca0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
18cb0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
18cc0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
18cd0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18ce0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
18cf0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
18d00 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
18d10 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
18d20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
18d30 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
18d40 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18d50 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
18d60 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18d70 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
18d80 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
18d90 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18da0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
18db0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18dc0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
18dd0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
18de0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
18df0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18e00 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
18e10 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
18e20 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18e30 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
18e40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18e50 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
18e60 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
18e70 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
18e80 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
18e90 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
18ea0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18eb0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
18ec0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
18ed0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
18ee0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
18ef0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18f00 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
18f10 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
18f20 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
18f30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
18f40 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18f50 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
18f60 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
18f70 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18f80 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
18f90 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
18fa0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
18fb0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
18fc0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
18fd0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
18fe0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
18ff0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19000 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
19010 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
19020 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19030 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
19040 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
19050 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
19060 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
19070 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
19080 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
19090 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
190a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
190b0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
190c0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
190d0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
190e0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
190f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19100 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
19110 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
19120 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
19130 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
19140 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
19150 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
19160 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
19170 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
19180 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19190 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
191a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
191b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
191c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
191d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
191e0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
191f0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
19200 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
19210 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
19220 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
19230 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
19240 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
19250 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
19260 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
19270 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
19280 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
19290 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
192a0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
192b0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
192c0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
192d0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
192e0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
192f0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
19300 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
19310 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19320 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19330 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
19340 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
19350 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
19360 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19370 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
19380 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
19390 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
193a0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
193b0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
193c0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
193d0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
193e0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
193f0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second 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 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19420 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
19430 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
19440 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
19450 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
19460 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
19470 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
19480 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
19490 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
194a0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
194b0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
194c0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
194d0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
194e0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
194f0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
19500 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
19510 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19520 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
19530 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
19540 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
19550 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
19560 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
19570 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
19580 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
19590 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
195a0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
195b0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
195c0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
195d0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
195e0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
195f0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
19600 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
19610 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
19630 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
19640 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
19650 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19660 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
19670 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
19680 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
19690 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
196a0 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
196b0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
196c0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
196d0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
196e0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
196f0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
19700 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
19710 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
19720 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
19730 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
19740 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
19750 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
19760 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
19770 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
19780 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
19790 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
197a0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
197b0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
197c0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
197d0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
197e0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
197f0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
19800 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
19810 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
19820 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
19830 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
19840 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
19850 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
19860 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
19870 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
19880 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
19890 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
198a0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
198b0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
198c0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
198d0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
198e0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
198f0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
19900 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
19910 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19920 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
19930 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19940 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
19950 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
19960 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
19970 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
19980 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
19990 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
199a0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
199b0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
199c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
199d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
199e0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
199f0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
19a00 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
19a10 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19a20 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
19a30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
19a40 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19a50 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
19a60 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
19a70 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
19a80 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
19a90 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
19aa0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
19ab0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
19ac0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19ad0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
19ae0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19af0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
19b00 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
19b10 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
19b20 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
19b30 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
19b40 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
19b50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19b60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
19b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19b80 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
19b90 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ba0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19bb0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
19bc0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
19bd0 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
19be0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19bf0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
19c00 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
19c10 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
19c20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
19c30 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
19c40 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
19c50 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
19c60 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
19c70 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
19c80 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
19c90 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
19ca0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
19cb0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
19cc0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19cd0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
19ce0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
19cf0 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
19d00 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
19d10 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19d20 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
19d30 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
19d40 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
19d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19d60 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
19d70 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
19d80 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19d90 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
19da0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
19db0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
19dc0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
19dd0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
19de0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
19df0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
19e00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19e10 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19e20 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19e30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
19e40 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
19e50 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
19e60 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
19e70 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
19e80 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
19e90 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
19ea0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19eb0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
19ec0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
19ed0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
19ee0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
19ef0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
19f00 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
19f10 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
19f20 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
19f30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19f40 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
19f50 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
19f60 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
19f70 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
19f80 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
19f90 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
19fa0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
19fb0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
19fc0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19fd0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
19fe0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
19ff0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1a000 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1a010 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1a020 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1a030 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1a040 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a050 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1a060 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1a070 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1a080 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1a090 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1a0a0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1a0b0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1a0c0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1a0d0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1a0e0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1a0f0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1a100 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1a110 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a120 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1a130 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1a140 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1a150 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1a160 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1a170 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1a180 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1a190 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1a1a0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1a1b0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1a1c0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1a1d0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1a1e0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1a1f0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1a200 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1a210 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a220 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a230 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a240 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a250 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a260 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a270 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a280 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a290 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a2a0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a2b0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a2c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a2d0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a2e0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a2f0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a300 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a310 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a320 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a340 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a350 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a360 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a370 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a380 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a390 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a3a0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a3b0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a3c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a3d0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a3e0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a3f0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a400 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a410 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a420 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a430 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a440 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a450 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a460 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a470 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a480 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a490 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a4a0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a4b0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a4c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a4d0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a4e0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a4f0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a500 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a510 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a520 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a530 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a540 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a550 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a560 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a570 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a580 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a590 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a5a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a5b0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a5c0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a5d0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a5e0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a5f0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a600 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a610 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a620 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a630 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a640 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a650 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a660 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a670 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a680 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a690 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a6a0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a6b0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a6c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a6d0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a6e0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a6f0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a700 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a710 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a720 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a730 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a740 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a750 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a760 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a770 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a780 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a790 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a7a0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a7b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a7c0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a7d0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a7e0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a7f0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a800 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a810 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a820 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a830 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a840 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a850 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a860 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a870 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a880 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1a890 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a8a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1a8b0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a8c0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1a8d0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1a8e0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1a8f0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1a900 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1a910 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1a920 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1a930 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1a940 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1a950 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1a960 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1a970 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1a980 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1a990 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1a9a0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a9b0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1a9c0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1a9d0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1a9e0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1a9f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1aa00 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1aa10 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1aa20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1aa30 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1aa40 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1aa50 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1aa60 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1aa70 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1aa80 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1aa90 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1aaa0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1aab0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1aac0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1aad0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1aae0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1aaf0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1ab00 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1ab10 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1ab20 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1ab30 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ab40 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1ab50 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ab60 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1ab70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1ab80 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1ab90 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1aba0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1abb0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1abc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1abd0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1abe0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1abf0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1ac00 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1ac10 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1ac20 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1ac30 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1ac40 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1ac50 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1ac60 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1ac70 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1ac80 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1ac90 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1aca0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1acb0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1acc0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1acd0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1ace0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1acf0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1ad00 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1ad10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ad20 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ad30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ad40 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ad50 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1ad60 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1ad70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1ad80 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1ad90 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1ada0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1adb0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1adc0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1add0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1ade0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1adf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1ae00 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1ae10 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1ae20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1ae30 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1ae40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ae50 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1ae60 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ae70 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1ae80 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1ae90 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1aea0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1aeb0 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1aec0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1aed0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1aee0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1aef0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1af00 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1af10 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1af20 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1af30 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1af40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1af50 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1af60 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1af70 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1af80 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1af90 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1afa0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1afb0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1afc0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1afd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1afe0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1aff0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1b000 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1b010 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1b020 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1b030 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1b040 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1b050 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1b060 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1b070 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1b080 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1b090 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1b0a0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1b0b0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1b0c0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1b0d0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1b0e0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1b0f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1b100 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1b110 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1b120 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1b130 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1b140 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1b150 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1b160 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1b170 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1b180 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1b190 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1b1a0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1b1b0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1b1c0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1b1d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1b1e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b1f0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1b200 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1b210 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1b220 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1b230 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1b240 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1b250 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b260 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1b270 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1b280 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1b290 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1b2a0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b2b0 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1b2c0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1b2d0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1b2e0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1b2f0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1b300 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1b310 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1b320 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1b330 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1b340 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1b350 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1b360 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1b370 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b380 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1b390 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1b3a0 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1b3b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b3c0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1b3d0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1b3e0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1b3f0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1b400 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1b410 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1b420 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1b430 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1b440 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b450 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1b460 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1b470 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1b480 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1b490 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1b4a0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1b4b0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1b4c0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1b4d0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1b4e0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1b4f0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1b500 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1b510 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1b520 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1b530 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1b540 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1b550 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b560 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1b570 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1b580 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1b590 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1b5a0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1b5b0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1b5c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1b5d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1b5e0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1b5f0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1b600 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1b610 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1b620 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b630 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b640 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1b650 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1b660 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b670 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1b680 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1b690 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1b6a0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1b6b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b6c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b6d0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1b6e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1b6f0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1b700 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1b710 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1b720 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1b730 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1b740 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1b750 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1b760 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b770 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1b780 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1b790 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1b7a0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1b7b0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1b7c0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1b7d0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1b7e0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b7f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b800 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b810 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b820 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b830 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1b840 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b850 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1b860 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1b870 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1b880 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1b890 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1b8a0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1b8b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b8c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b8d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b8e0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1b8f0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1b900 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b910 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1b920 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1b930 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1b940 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1b950 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1b960 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1b970 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1b980 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1b990 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1b9a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1b9b0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1b9c0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b9d0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1b9e0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1b9f0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1ba00 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1ba10 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1ba20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1ba30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1ba40 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1ba50 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1ba60 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1ba70 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1ba80 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1ba90 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1baa0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1bab0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1bac0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1bad0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1bae0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1baf0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1bb00 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1bb10 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1bb20 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1bb30 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1bb40 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1bb50 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1bb60 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1bb70 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1bb80 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1bb90 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1bba0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1bbb0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1bbc0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1bbd0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1bbe0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1bbf0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1bc00 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1bc10 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1bc20 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1bc30 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1bc40 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1bc50 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1bc60 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1bc70 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1bc80 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1bc90 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1bca0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1bcb0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1bcc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1bcd0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1bce0 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
1bcf0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1bd00 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1bd10 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
1bd20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1bd30 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bd40 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
1bd50 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1bd60 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1bd70 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1bd80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bd90 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1bda0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1bdb0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1bdc0 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1bdd0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1bde0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1bdf0 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1be00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1be10 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1be20 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1be30 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1be40 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1be50 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1be60 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1be70 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1be80 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1be90 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1bea0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1beb0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1bec0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1bed0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1bee0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1bef0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1bf00 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1bf10 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1bf20 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1bf30 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1bf40 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1bf50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1bf60 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1bf70 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1bf80 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1bf90 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bfa0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1bfb0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1bfc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1bfd0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1bfe0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1bff0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1c000 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1c010 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c020 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1c030 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1c040 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1c050 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1c060 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c070 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1c080 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1c090 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1c0a0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1c0b0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1c0c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c0d0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1c0e0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1c0f0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1c100 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1c110 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1c120 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1c130 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1c140 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1c150 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1c160 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1c170 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1c180 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1c190 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1c1a0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1c1b0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1c1c0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1c1d0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1c1e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1c1f0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1c200 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1c210 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1c220 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1c230 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1c240 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1c250 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1c260 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1c270 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1c280 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1c290 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1c2a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c2b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1c2c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c2d0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1c2e0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1c2f0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1c300 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1c310 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c320 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1c330 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1c340 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1c350 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c360 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1c370 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1c380 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1c390 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c3a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c3b0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1c3c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1c3d0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1c3e0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1c3f0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1c400 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1c410 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1c420 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1c430 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c440 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1c450 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1c460 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c470 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1c480 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1c490 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1c4a0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1c4b0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1c4c0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1c4d0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1c4e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1c4f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c500 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c510 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1c520 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c530 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c540 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1c550 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1c560 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1c570 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1c580 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1c590 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1c5a0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1c5b0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1c5c0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1c5d0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1c5e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1c5f0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1c600 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1c610 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1c620 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1c630 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1c640 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c650 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c670 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1c680 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1c690 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1c6a0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1c6b0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1c6c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1c6d0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1c6e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c6f0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1c700 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1c710 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1c720 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1c730 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1c740 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1c750 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1c760 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c770 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c780 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c790 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c7a0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c7b0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c7c0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c7d0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c7e0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c7f0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c800 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c820 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c830 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c840 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1c850 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1c860 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1c870 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c880 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1c890 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1c8a0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1c8b0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1c8c0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1c8d0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1c8e0 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1c8f0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c900 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1c910 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1c920 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1c930 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1c940 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1c950 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1c960 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1c970 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1c980 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1c990 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1c9a0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1c9b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1c9c0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1c9d0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1c9e0 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1c9f0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1ca00 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1ca10 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1ca20 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ca30 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1ca40 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1ca50 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1ca60 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1ca70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1ca80 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1ca90 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1caa0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1cab0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1cac0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1cad0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cae0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1caf0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1cb00 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1cb10 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1cb20 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1cb30 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1cb40 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1cb50 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1cb60 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1cb70 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1cb80 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1cb90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1cbb0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1cbc0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1cbd0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1cbe0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1cbf0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1cc00 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1cc10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cc20 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1cc30 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1cc40 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1cc50 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1cc60 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1cc70 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1cc80 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1cc90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cca0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1ccb0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1ccc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1ccd0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1cce0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1ccf0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1cd00 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1cd10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1cd20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cd30 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1cd40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cd50 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1cd60 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1cd70 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1cd80 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1cd90 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1cda0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cdb0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1cdc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1cdd0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1cde0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1cdf0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1ce00 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1ce10 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1ce20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1ce30 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1ce40 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ce50 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1ce60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ce70 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1ce80 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1ce90 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1cea0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1ceb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1cec0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1ced0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1cee0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1cef0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1cf00 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1cf10 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1cf20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cf30 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1cf40 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cf50 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1cf60 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1cf70 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1cf80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1cf90 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1cfa0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1cfb0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1cfc0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cfd0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1cfe0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1cff0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d000 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d010 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1d020 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d030 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1d040 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
1d050 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d060 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d070 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
1d080 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1d090 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1d0a0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1d0b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d0c0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1d0d0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1d0e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1d0f0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1d100 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1d110 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1d120 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1d130 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1d140 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1d150 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1d160 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1d170 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1d180 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1d190 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1d1a0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1d1b0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1d1c0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1d1d0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1d1e0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1d1f0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1d200 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1d210 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1d220 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1d230 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1d240 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1d250 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1d260 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d270 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1d280 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1d290 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1d2a0 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  ** ^If N is less
1d2b0 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20   than one, then 
1d2c0 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  P can be a NULL 
1d2d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d2e0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1d2f0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1d300 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1d310 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1d320 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1d330 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74  less than one, t
1d340 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20  hen the PRNG is 
1d350 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1d360 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69  domness.** obtai
1d370 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1d380 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1d390 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1d3a0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1d3b0 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1d3c0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1d3d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1d3e0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1d3f0 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ore then.** the 
1d400 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1d410 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1d420 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1d430 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1d440 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1d450 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1d460 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1d470 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1d480 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1d490 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1d4a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1d4b0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1d4c0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1d4d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d4e0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1d4f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d500 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1d510 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1d520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1d530 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1d540 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1d550 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1d560 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d570 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1d580 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1d590 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1d5a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1d5b0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1d5c0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1d5d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1d5e0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d5f0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1d600 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1d610 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1d620 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1d630 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1d640 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1d650 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1d660 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1d670 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1d680 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1d690 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d6a0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1d6b0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1d6c0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1d6d0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1d6e0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1d6f0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1d700 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1d710 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1d720 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1d730 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1d740 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1d750 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1d760 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1d770 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1d780 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1d790 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1d7a0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1d7b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1d7c0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1d7d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1d7e0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1d7f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1d800 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1d810 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1d820 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1d830 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1d840 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1d850 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1d860 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d870 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d880 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1d890 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1d8a0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d8b0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d8c0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1d8d0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d8e0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1d8f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1d900 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1d910 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1d920 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d930 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d940 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1d950 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d960 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1d970 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1d980 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1d990 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1d9a0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1d9b0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1d9c0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1d9d0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1d9e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1d9f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1da00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1da10 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1da20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1da30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1da40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1da50 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1da60 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1da70 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1da80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1da90 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1daa0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1dab0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1dac0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1dad0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1dae0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1daf0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1db00 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1db10 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1db20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1db30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1db40 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1db50 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1db60 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1db70 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1db80 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1db90 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1dba0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1dbb0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1dbc0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1dbd0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1dbe0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1dbf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dc00 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1dc10 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1dc20 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1dc30 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1dc40 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1dc50 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1dc60 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1dc70 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1dc80 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1dc90 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1dca0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1dcb0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1dcc0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1dcd0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1dce0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1dcf0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1dd00 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1dd10 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1dd20 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1dd30 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1dd40 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1dd50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1dd60 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1dd70 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1dd80 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1dd90 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1dda0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1ddb0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1ddc0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1ddd0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1dde0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1ddf0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1de00 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1de10 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1de20 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1de30 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1de40 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1de50 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1de60 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1de70 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1de80 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1de90 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1dea0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1deb0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1dec0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1ded0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1dee0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1def0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1df00 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1df10 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1df20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1df30 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1df40 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1df50 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1df60 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1df70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1df80 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1df90 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1dfa0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1dfb0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1dfc0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1dfd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1dfe0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1dff0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1e000 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1e010 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1e020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1e030 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1e040 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1e050 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1e060 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1e070 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1e080 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1e090 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1e0a0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1e0b0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1e0c0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1e0d0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1e0e0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1e0f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1e100 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1e110 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1e120 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1e130 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1e140 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1e150 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1e160 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1e170 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1e180 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1e190 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1e1a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e1b0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1e1c0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1e1d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e1e0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1e1f0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1e200 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1e210 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e220 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1e230 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1e240 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1e250 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1e260 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1e270 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e280 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1e290 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1e2a0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1e2b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e2c0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1e2d0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1e2e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1e2f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1e300 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e310 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1e320 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1e330 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1e340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1e350 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1e360 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1e370 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1e380 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1e390 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e3a0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1e3b0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1e3c0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1e3d0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1e3e0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1e3f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e400 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1e410 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1e420 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1e430 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1e440 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1e450 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1e460 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1e470 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1e480 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1e490 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1e4a0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1e4b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e4c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1e4d0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1e4e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e4f0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1e500 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1e510 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1e520 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1e530 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1e540 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1e550 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1e560 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1e570 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1e580 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1e590 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1e5a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e5b0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1e5c0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1e5d0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1e5e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1e5f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e600 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1e610 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1e620 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1e630 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1e640 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e650 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1e660 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1e670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1e680 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1e690 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1e6a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e6b0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e6c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1e6d0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1e6e0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1e6f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1e700 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1e710 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1e720 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1e730 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1e740 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1e750 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1e760 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1e770 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e780 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e790 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e7a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e7b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1e7c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1e7d0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1e7e0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1e7f0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1e800 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1e810 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e820 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e830 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e840 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e850 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e860 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e870 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e880 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1e890 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1e8a0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1e8b0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1e8c0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1e8d0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1e8e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e8f0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1e900 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e910 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e920 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1e930 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1e940 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1e950 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1e960 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1e970 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1e980 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1e990 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1e9a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1e9b0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e9c0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1e9d0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1e9e0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1e9f0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1ea00 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1ea10 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1ea20 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1ea30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ea40 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1ea50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1ea60 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1ea70 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1ea80 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1ea90 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1eaa0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1eab0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1eac0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1ead0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1eae0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1eaf0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1eb00 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1eb10 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1eb20 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1eb30 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1eb40 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1eb50 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1eb60 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1eb70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1eb80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1eb90 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1eba0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1ebb0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1ebc0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1ebd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1ebe0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ebf0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1ec00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1ec10 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ec20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1ec30 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ec40 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ec50 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1ec60 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1ec70 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1ec80 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ec90 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1eca0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ecb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ecc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1ecd0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1ece0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1ecf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ed00 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1ed10 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1ed20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ed30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ed40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ed50 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1ed60 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1ed70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ed80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ed90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1eda0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1edb0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1edc0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1edd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ede0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1edf0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1ee00 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1ee10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ee20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ee30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ee40 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1ee50 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1ee60 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ee70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ee80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ee90 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1eea0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1eeb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1eec0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1eed0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1eee0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1eef0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1ef00 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1ef10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ef20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1ef30 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1ef40 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1ef50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ef60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ef70 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1ef80 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1ef90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1efa0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1efb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1efc0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1efd0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1efe0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1eff0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f000 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f010 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1f020 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1f030 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f040 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f060 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1f070 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1f080 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f090 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f0a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f0b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1f0c0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1f0d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f0e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f0f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f100 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1f110 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1f120 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f130 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f150 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1f160 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1f170 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f180 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f1a0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1f1b0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1f1c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1f1d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f1e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f1f0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1f200 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1f210 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f220 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1f240 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1f250 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1f260 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f270 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f280 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1f290 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1f2a0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1f2b0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1f2c0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1f2d0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1f2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f2f0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1f300 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f310 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f320 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1f330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f340 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1f350 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f360 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f370 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1f380 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1f390 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1f3a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f3b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f3c0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1f3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1f3e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f3f0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f400 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f410 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1f420 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1f430 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1f440 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f460 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1f470 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1f480 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f490 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f4a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f4b0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1f4c0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1f4d0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f4e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f4f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f500 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1f510 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1f520 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f530 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f550 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1f560 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1f570 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f5a0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1f5b0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1f5c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1f5d0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1f5e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f5f0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1f600 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1f610 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f620 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f640 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1f650 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1f660 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1f670 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1f680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f690 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1f6a0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1f6b0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1f6c0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1f6d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1f6e0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1f6f0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1f700 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
1f710 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
1f720 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
1f730 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
1f740 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f750 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
1f760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f770 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f780 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f790 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f7a0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f7b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f7c0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f7d0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f7e0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f7f0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f800 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f810 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f820 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f830 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f840 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f850 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f860 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f870 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f880 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1f890 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f8a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1f8b0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1f8c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1f8d0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1f8e0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1f8f0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1f900 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1f910 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1f920 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1f930 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1f940 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f950 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1f960 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1f970 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1f980 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1f990 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1f9a0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1f9b0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1f9c0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1f9d0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1f9e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1f9f0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1fa00 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1fa10 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1fa20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1fa30 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1fa40 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1fa50 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1fa60 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1fa70 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1fa80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1fa90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1faa0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1fab0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1fac0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1fad0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1fae0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1faf0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fb00 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1fb10 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1fb20 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1fb30 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1fb40 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1fb50 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1fb60 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1fb70 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1fb80 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1fb90 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1fba0 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1fbb0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1fbc0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1fbd0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1fbe0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1fbf0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1fc00 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1fc10 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fc20 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fc30 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fc40 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fc50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fc60 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fc70 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fc80 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fc90 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fca0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fcb0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1fcc0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fcd0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fce0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fcf0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fd00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fd10 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1fd20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1fd30 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1fd40 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1fd50 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1fd60 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1fd70 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1fd80 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1fd90 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1fda0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1fdb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1fdc0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1fdd0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1fde0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1fdf0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1fe00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fe10 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1fe20 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1fe30 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1fe40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1fe50 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1fe60 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1fe70 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1fe80 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1fe90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1fea0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1feb0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1fec0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1fed0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1fee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1fef0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1ff00 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1ff10 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1ff20 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1ff30 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1ff40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1ff50 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1ff60 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1ff70 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1ff80 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1ff90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1ffa0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1ffb0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
1ffc0 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
1ffd0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1ffe0 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1fff0 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
20000 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
20010 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
20020 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
20030 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
20040 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
20050 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
20060 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
20070 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
20080 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
20090 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
200a0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
200b0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
200c0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
200d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
200e0 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
200f0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
20100 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
20110 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
20120 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
20130 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
20140 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
20150 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
20160 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
20170 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
20180 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
20190 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
201a0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
201b0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
201c0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
201d0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
201e0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
201f0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
20200 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
20210 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
20220 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
20230 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
20240 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
20250 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
20260 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
20270 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20280 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20290 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
202a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
202b0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
202c0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
202d0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
202e0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
202f0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
20300 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20310 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
20320 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
20330 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
20340 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
20350 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
20360 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
20370 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
20380 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
20390 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
203a0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
203b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
203c0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
203d0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
203e0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
203f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
20400 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
20410 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
20420 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
20430 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
20440 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
20450 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
20460 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
20470 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
20480 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20490 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
204a0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
204b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
204c0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
204d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
204e0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
204f0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20500 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
20510 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
20520 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
20530 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
20540 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
20550 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
20560 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
20570 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
20580 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
20590 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
205a0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
205b0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
205c0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
205d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
205e0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
205f0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
20600 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20610 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
20620 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
20630 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
20640 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
20650 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
20660 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
20670 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
20680 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
20690 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
206a0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
206b0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
206c0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
206d0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
206e0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
206f0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
20700 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
20710 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
20720 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
20730 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
20740 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
20750 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
20760 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
20770 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
20780 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
20790 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
207a0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
207b0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
207c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
207d0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
207e0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
207f0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
20800 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
20810 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
20820 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
20830 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
20840 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
20850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
20860 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
20870 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
20880 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
20890 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
208a0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
208b0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
208c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
208d0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
208e0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
208f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
20900 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
20910 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
20920 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
20930 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
20940 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
20950 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
20960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
20970 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
20980 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
20990 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
209a0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
209b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
209c0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
209d0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
209e0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
209f0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
20a00 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
20a10 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
20a20 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20a30 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
20a40 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20a50 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
20a60 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20a70 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
20a80 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
20a90 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
20aa0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
20ab0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20ac0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
20ad0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
20ae0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
20af0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
20b00 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
20b10 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
20b20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
20b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20b40 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
20b50 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20b60 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20b70 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
20b80 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
20b90 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
20ba0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
20bb0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
20bc0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
20bd0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
20be0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
20bf0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
20c00 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
20c10 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
20c20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
20c30 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20c40 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20c50 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
20c60 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
20c70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20c80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20c90 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
20ca0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
20cb0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
20cc0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
20cd0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
20ce0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
20cf0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
20d00 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
20d10 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20d20 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20d30 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
20d40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
20d50 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
20d60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20d70 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
20d80 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
20d90 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
20da0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
20db0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
20dc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
20dd0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
20de0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
20df0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
20e00 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
20e10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
20e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
20e30 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
20e40 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
20e60 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
20e70 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
20e80 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
20e90 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
20ea0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
20eb0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
20ec0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
20ed0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
20ee0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
20ef0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
20f00 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
20f10 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
20f30 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
20f40 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
20f50 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
20f60 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
20f70 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
20f80 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
20f90 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
20fa0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
20fb0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20fc0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
20fd0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
20fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20ff0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
21000 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
21010 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
21020 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
21030 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
21040 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
21050 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
21060 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
21070 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
21080 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
21090 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
210a0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
210b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
210c0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
210d0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
210e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
210f0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
21100 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
21110 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21120 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21130 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
21140 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
21150 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
21160 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
21170 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21180 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21190 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
211a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
211b0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
211c0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
211d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
211e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
211f0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
21200 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21210 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
21220 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
21230 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
21240 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
21250 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
21260 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
21270 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
21280 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
21290 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
212a0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
212b0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
212c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
212d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
212e0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
212f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
21300 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
21310 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
21320 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
21330 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
21340 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
21350 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
21360 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
21370 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
21380 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
21390 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
213a0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
213b0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
213c0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
213d0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
213e0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
213f0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
21400 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
21410 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21420 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
21430 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21440 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
21450 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
21460 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
21470 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
21480 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
21490 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
214a0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
214b0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
214c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
214d0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
214e0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
214f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
21500 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
21510 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
21520 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
21530 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21540 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
21550 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
21560 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
21570 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
21580 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
21590 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
215a0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
215b0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
215c0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
215d0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
215e0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
215f0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
21600 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
21610 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
21620 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
21630 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
21640 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
21650 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
21660 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
21670 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
21680 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
21690 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
216a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
216b0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
216c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
216d0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
216e0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
216f0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
21700 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
21710 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
21720 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
21730 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
21740 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
21750 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
21760 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
21770 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
21780 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
21790 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
217a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
217b0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
217c0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
217d0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
217e0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
217f0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
21800 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
21810 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
21820 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21830 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
21840 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
21850 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
21860 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
21870 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
21880 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
21890 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
218a0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
218b0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
218c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
218d0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
218e0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
218f0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
21900 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
21910 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
21920 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
21930 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
21940 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
21950 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
21960 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
21970 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
21980 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
21990 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
219a0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
219b0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
219c0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
219d0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
219e0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
219f0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
21a00 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
21a10 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
21a20 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
21a30 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21a40 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
21a50 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
21a60 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
21a70 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
21a80 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
21a90 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
21aa0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
21ab0 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
21ac0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
21ad0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
21ae0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
21af0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
21b00 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
21b10 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
21b20 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
21b30 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
21b40 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
21b50 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
21b60 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
21b70 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
21b80 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
21b90 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
21ba0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
21bb0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
21bc0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
21bd0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
21be0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
21bf0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
21c00 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
21c10 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
21c20 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
21c30 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
21c40 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
21c50 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
21c60 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
21c70 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
21c80 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
21c90 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
21ca0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
21cb0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
21cc0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
21cd0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
21ce0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
21cf0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
21d00 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
21d10 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
21d20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
21d30 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
21d40 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
21d50 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
21d60 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
21d70 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
21d80 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
21d90 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
21da0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21db0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21dc0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
21dd0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
21de0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
21df0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
21e00 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
21e10 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
21e20 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
21e30 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
21e40 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
21e50 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
21e60 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
21e70 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
21e80 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
21e90 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
21ea0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21eb0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
21ec0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
21ed0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
21ee0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
21ef0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
21f00 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
21f10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
21f20 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21f30 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
21f40 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
21f50 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
21f60 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
21f70 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21f80 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
21f90 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
21fa0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
21fb0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
21fc0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
21fd0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
21fe0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
21ff0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
22000 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
22010 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
22020 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
22030 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22040 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
22050 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
22060 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
22070 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
22080 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
22090 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
220a0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
220b0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
220c0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
220d0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
220e0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
220f0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
22100 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
22110 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
22120 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
22130 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
22140 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
22150 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
22160 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
22170 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
22180 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
22190 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
221a0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
221b0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
221c0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
221d0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
221e0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
221f0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
22200 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
22210 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
22220 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
22230 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22240 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
22250 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
22260 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
22270 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
22280 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
22290 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
222a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
222b0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
222c0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
222d0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
222e0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
222f0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
22300 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22310 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22320 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
22330 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
22340 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
22350 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
22360 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
22370 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
22380 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
22390 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
223a0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
223b0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
223c0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
223d0 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
223e0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
223f0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
22400 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
22410 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
22420 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
22430 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
22440 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22450 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
22460 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
22470 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
22480 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
22490 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
224a0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
224b0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
224c0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
224d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
224e0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
224f0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
22500 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
22510 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
22520 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
22530 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
22540 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
22550 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
22560 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
22570 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
22580 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
22590 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
225a0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
225b0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
225c0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
225d0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
225e0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
225f0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
22600 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
22610 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22620 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
22630 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
22640 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
22650 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
22660 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
22670 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22680 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
22690 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
226a0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
226b0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
226c0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
226d0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
226e0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
226f0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
22700 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
22710 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
22720 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
22730 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
22740 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
22750 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
22760 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
22770 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
22780 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
22790 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
227a0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
227b0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
227c0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
227d0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
227e0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
227f0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
22800 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
22810 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
22820 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
22830 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
22840 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
22850 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
22860 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
22870 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
22880 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
22890 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
228a0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
228b0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
228c0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
228d0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
228e0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
228f0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
22900 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
22910 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
22920 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
22930 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
22940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
22950 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
22960 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
22970 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
22980 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
22990 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
229a0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
229b0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
229c0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
229d0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
229e0 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
229f0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
22a00 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
22a10 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
22a20 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
22a30 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
22a40 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
22a50 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
22a60 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
22a70 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
22a80 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
22a90 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22aa0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
22ab0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
22ac0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
22ad0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
22ae0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
22af0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
22b00 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
22b10 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
22b20 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
22b30 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
22b40 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
22b50 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
22b60 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
22b70 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
22b80 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
22b90 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
22ba0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
22bb0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
22bc0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
22bd0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
22be0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
22bf0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
22c00 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
22c10 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
22c20 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
22c30 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
22c40 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
22c50 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
22c60 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
22c70 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
22c80 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
22c90 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
22ca0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
22cb0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
22cc0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
22cd0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
22ce0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
22cf0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
22d00 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
22d10 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
22d20 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
22d30 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
22d40 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
22d50 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
22d60 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
22d70 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
22d80 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
22d90 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
22da0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
22db0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
22dc0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
22dd0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
22de0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
22df0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
22e00 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
22e10 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
22e20 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
22e30 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
22e40 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
22e50 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
22e60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22e70 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
22e80 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
22e90 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
22ea0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
22eb0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
22ec0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
22ed0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
22ee0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
22ef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
22f00 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
22f10 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
22f20 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
22f30 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
22f40 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
22f50 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
22f60 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
22f70 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
22f80 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
22f90 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
22fa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
22fb0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
22fc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
22fd0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
22fe0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
22ff0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
23000 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23010 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
23020 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
23030 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23040 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
23050 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
23060 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23070 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23080 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
23090 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
230a0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
230b0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
230c0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
230d0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
230e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
230f0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
23100 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
23110 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
23120 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
23130 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
23140 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
23150 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
23160 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
23170 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23180 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
23190 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
231a0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
231b0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
231c0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
231d0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
231e0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
231f0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
23200 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
23210 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
23220 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
23230 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
23240 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
23250 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
23260 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23270 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
23280 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
23290 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
232a0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
232b0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
232c0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
232d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
232e0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
232f0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
23300 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
23310 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
23320 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
23330 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
23340 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
23350 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
23360 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
23370 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
23380 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
23390 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
233a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
233b0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
233c0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
233d0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
233e0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
233f0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
23400 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
23410 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
23420 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23430 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23440 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
23450 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
23460 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
23470 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
23480 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
23490 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
234a0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
234b0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
234c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
234d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
234e0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
234f0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
23500 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23510 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
23520 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
23530 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
23540 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
23550 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
23560 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
23570 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23580 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23590 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
235a0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
235b0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
235c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
235d0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
235e0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
235f0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
23600 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
23610 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
23620 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
23630 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
23640 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
23650 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
23660 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
23670 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
23680 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
23690 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
236a0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
236b0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
236c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
236d0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
236e0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
236f0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
23700 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
23710 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
23720 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
23730 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
23740 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
23750 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
23760 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
23770 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
23780 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
23790 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
237a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
237b0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
237c0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
237d0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
237e0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
237f0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
23800 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23810 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
23820 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
23830 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
23840 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
23850 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
23860 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
23870 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
23880 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
23890 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
238a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
238b0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
238c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
238d0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
238e0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
238f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23900 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23910 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23920 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23930 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
23940 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23950 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
23960 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
23970 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
23980 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
23990 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
239a0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
239b0 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
239c0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
239d0 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
239e0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
239f0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
23a00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23a10 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
23a20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23a30 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
23a40 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
23a50 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23a60 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
23a70 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
23a80 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
23a90 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
23aa0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
23ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
23ac0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
23ad0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
23ae0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23af0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
23b00 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
23b10 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
23b20 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23b30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
23b40 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
23b50 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
23b60 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
23b70 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
23b80 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
23b90 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
23ba0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23bb0 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
23bc0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23bd0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
23be0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
23bf0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
23c00 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
23c10 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
23c20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
23c30 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
23c40 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
23c50 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
23c60 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
23c70 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
23c80 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
23c90 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
23ca0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
23cb0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
23cc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
23cd0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
23ce0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
23cf0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
23d00 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
23d10 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
23d20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
23d30 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
23d40 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
23d50 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
23d60 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
23d70 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
23d80 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
23d90 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
23da0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23db0 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
23dc0 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
23dd0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
23de0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
23df0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
23e00 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
23e10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
23e20 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
23e30 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
23e40 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
23e50 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
23e60 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
23e70 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
23e80 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
23e90 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
23ea0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
23eb0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
23ec0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
23ed0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
23ee0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
23ef0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
23f00 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
23f10 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
23f20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
23f30 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
23f40 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
23f50 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
23f60 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
23f70 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
23f80 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
23f90 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
23fa0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
23fb0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
23fc0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
23fd0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
23fe0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
23ff0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24000 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
24010 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
24020 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
24030 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
24040 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
24050 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
24060 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
24070 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
24080 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
24090 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
240a0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
240b0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
240c0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
240d0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
240e0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
240f0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
24100 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
24110 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
24120 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
24130 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
24140 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
24150 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
24160 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
24170 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
24180 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
24190 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
241a0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
241b0 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
241c0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
241d0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
241e0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
241f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
24200 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
24210 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
24220 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
24230 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24240 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
24250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24260 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
24270 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
24280 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
24290 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
242a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
242b0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
242c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
242d0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
242e0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
242f0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
24300 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
24310 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
24320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
24330 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
24340 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
24350 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
24360 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
24370 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
24380 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
24390 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
243a0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
243b0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
243c0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
243d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
243e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
243f0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
24400 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
24410 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
24420 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
24430 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
24440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
24450 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
24460 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
24470 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
24480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24490 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
244a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
244b0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
244c0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
244d0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
244e0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
244f0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
24500 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
24510 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24520 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
24530 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24540 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
24550 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
24560 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
24570 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
24580 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24590 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
245a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
245b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
245c0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
245d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
245e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
245f0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
24600 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
24610 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24620 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
24630 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24640 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
24650 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
24660 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
24670 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
24680 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24690 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
246a0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
246b0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
246c0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
246d0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
246e0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
246f0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
24700 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
24710 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24720 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24730 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
24740 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24750 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
24760 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
24770 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
24780 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
24790 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
247a0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
247b0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
247c0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
247d0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
247e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
247f0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
24800 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
24810 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
24820 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
24830 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
24840 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
24850 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
24860 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
24870 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
24880 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
24890 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
248a0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
248b0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
248c0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
248d0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
248e0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
248f0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
24900 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
24910 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
24920 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
24930 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
24940 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
24950 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
24960 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
24970 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
24980 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24990 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
249a0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
249b0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
249c0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
249d0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
249e0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
249f0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
24a00 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
24a10 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
24a20 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
24a30 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
24a40 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
24a50 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
24a60 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
24a70 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
24a80 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
24a90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
24aa0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
24ab0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
24ac0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
24ad0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
24ae0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
24af0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
24b00 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
24b10 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
24b20 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
24b30 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
24b40 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
24b50 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
24b60 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
24b70 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
24b80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
24b90 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
24ba0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
24bb0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
24bc0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
24bd0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
24be0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
24bf0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
24c00 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
24c10 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
24c20 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
24c30 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
24c40 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
24c50 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
24c60 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
24c70 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
24c80 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
24c90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
24ca0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
24cb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
24cc0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
24cd0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
24ce0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
24cf0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
24d00 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
24d10 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
24d20 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
24d30 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
24d40 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
24d50 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
24d60 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
24d70 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
24d80 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
24d90 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
24da0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
24db0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
24dc0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
24dd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
24de0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
24df0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
24e00 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
24e10 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
24e20 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
24e30 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
24e40 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
24e50 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
24e60 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
24e70 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
24e80 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
24e90 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
24ea0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
24eb0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
24ec0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
24ed0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
24ee0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
24ef0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
24f00 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
24f10 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
24f20 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
24f30 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
24f40 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
24f50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24f60 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
24f70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24f80 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
24f90 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
24fa0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
24fb0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
24fc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24fd0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
24fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24ff0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
25000 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25010 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
25020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
25030 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
25040 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25050 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
25060 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25070 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
25080 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25090 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
250a0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
250b0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
250c0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
250d0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
250e0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
250f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
25100 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
25110 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
25120 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
25130 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
25140 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25150 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
25160 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25170 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
25180 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25190 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
251a0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
251b0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
251c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
251d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
251e0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
251f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25200 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
25210 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25220 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25230 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
25240 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
25250 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
25260 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25270 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
25280 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25290 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
252a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
252b0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
252c0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
252d0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
252e0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
252f0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
25300 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
25310 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
25320 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
25330 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
25340 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
25350 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
25360 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
25370 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
25380 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25390 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
253a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
253b0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
253c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
253d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
253e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
253f0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
25400 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25410 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25420 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25430 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
25440 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25450 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25460 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
25470 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
25480 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
25490 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
254a0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
254b0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
254c0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
254d0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
254e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
254f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
25500 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
25510 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
25520 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
25530 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
25540 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25550 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25560 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
25570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25580 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
25590 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
255a0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
255b0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
255c0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
255d0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
255e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
255f0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
25600 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25610 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25620 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25630 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
25640 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
25650 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
25660 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
25670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25680 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
25690 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
256a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
256b0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
256c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
256d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
256e0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
256f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
25700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25710 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25730 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
25740 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25750 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
25760 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
25770 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
25780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25790 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
257a0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
257b0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
257c0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
257d0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
257e0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
257f0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
25800 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
25810 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
25820 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
25830 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25840 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
25850 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
25860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25870 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
25880 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
25890 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
258a0 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
258b0 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
258c0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
258d0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
258e0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
258f0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
25900 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
25910 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
25920 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
25930 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
25940 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
25950 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
25960 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
25970 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
25980 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
25990 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
259a0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
259b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
259c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
259d0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
259e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
259f0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
25a00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
25a10 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
25a20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
25a30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
25a40 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
25a50 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
25a60 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
25a70 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
25a80 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
25a90 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
25aa0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
25ab0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25ac0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
25ad0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
25ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25af0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
25b00 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
25b10 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
25b20 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
25b30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
25b40 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
25b50 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
25b60 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
25b70 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
25b80 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
25b90 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
25ba0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
25bb0 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
25bc0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
25bd0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
25be0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
25bf0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
25c00 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
25c10 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
25c20 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
25c30 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
25c40 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
25c50 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
25c60 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
25c70 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
25c80 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
25c90 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
25ca0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
25cb0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
25cc0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
25cd0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
25ce0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
25cf0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
25d00 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
25d10 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
25d20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25d30 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
25d40 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
25d50 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
25d60 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
25d70 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61  bytes as this sa
25d80 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  ves SQLite from 
25d90 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b  having to.** mak
25da0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
25db0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a  input string..**
25dc0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
25dd0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
25de0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
25df0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
25e00 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
25e10 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
25e20 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
25e30 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
25e40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
25e50 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
25e60 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
25e70 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
25e80 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
25e90 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
25ea0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
25eb0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
25ec0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
25ed0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
25ee0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
25ef0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
25f00 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
25f10 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
25f20 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
25f30 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
25f40 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
25f50 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
25f60 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
25f70 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
25f80 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
25f90 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
25fa0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
25fb0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
25fc0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
25fd0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
25fe0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
25ff0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
26000 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
26010 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
26020 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
26030 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
26040 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
26050 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
26060 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
26070 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
26080 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
26090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
260a0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
260b0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
260c0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
260d0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
260e0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
260f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26100 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26110 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
26120 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
26130 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
26140 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
26150 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
26160 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
26170 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
26180 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
26190 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
261a0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
261b0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
261c0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
261d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
261e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
261f0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
26200 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
26210 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
26220 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
26230 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
26240 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
26250 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
26260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
26270 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
26280 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
26290 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
262a0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
262b0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
262c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
262d0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
262e0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
262f0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
26300 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
26310 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
26320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26330 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
26340 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
26350 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
26360 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
26370 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
26380 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
26390 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
263a0 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
263b0 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
263c0 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
263d0 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
263e0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
263f0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
26400 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
26410 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
26420 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
26430 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
26440 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
26450 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
26460 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
26470 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
26480 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
26490 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
264a0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
264b0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
264c0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
264d0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
264e0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
264f0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
26500 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
26510 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
26520 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
26530 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
26540 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
26550 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
26560 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
26570 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
26580 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
26590 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
265a0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
265b0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
265c0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
265d0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
265e0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
265f0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
26600 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
26610 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
26620 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
26630 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
26640 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
26650 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
26660 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
26670 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
26680 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
26690 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
266a0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
266b0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
266c0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
266d0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
266e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
266f0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
26700 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
26710 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
26720 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
26730 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
26740 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
26750 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
26760 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
26770 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
26780 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
26790 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
267a0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
267b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
267c0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
267d0 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
267e0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
267f0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
26800 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
26810 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
26820 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
26830 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
26840 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
26850 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
26860 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
26870 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
26880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26890 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
268a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
268b0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
268c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
268d0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
268e0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
268f0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
26900 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26910 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26920 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26930 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26940 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26950 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26960 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26970 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26980 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
26990 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
269a0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
269b0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
269c0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
269d0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
269e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
269f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26a00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26a10 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26a20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26a30 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
26a40 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26a60 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26a70 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26a80 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26a90 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26aa0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26ab0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26ac0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
26ad0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26ae0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26af0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26b00 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26b10 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
26b20 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26b30 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
26b40 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
26b50 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
26b60 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
26b70 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
26b80 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26b90 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26ba0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26bb0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26bc0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26bd0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26be0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26bf0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26c00 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
26c10 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26c20 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
26c30 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
26c40 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
26c50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26c60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
26c70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26c80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26c90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26ca0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
26cb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26cc0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26cd0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26cf0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
26d00 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
26d10 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
26d20 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
26d30 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
26d40 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26d50 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
26d60 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26d70 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26d80 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26d90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26da0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
26db0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
26dc0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
26dd0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
26de0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
26df0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
26e00 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
26e10 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
26e20 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
26e30 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
26e40 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
26e50 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
26e60 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
26e70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26e80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26e90 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
26ea0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26eb0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
26ec0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
26ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26ee0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
26ef0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
26f00 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
26f10 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
26f20 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26f30 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
26f40 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
26f50 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
26f60 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
26f70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f80 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
26f90 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
26fa0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
26fb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
26fc0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
26fd0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
26fe0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
26ff0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
27000 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
27010 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
27020 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
27030 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
27040 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
27050 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
27060 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
27070 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
27080 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
27090 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
270a0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
270b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
270c0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
270d0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
270e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
270f0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
27100 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
27110 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
27120 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
27130 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
27140 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
27150 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
27160 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
27170 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
27180 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
27190 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
271a0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
271b0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
271c0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
271d0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
271e0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
271f0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
27200 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
27210 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
27220 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
27230 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
27240 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
27250 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
27260 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27270 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27280 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
27290 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
272a0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
272b0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
272c0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
272d0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
272e0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
272f0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
27300 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
27310 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
27320 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
27330 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
27340 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
27350 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
27360 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
27370 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
27380 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
27390 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
273a0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
273b0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
273c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
273d0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
273e0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
273f0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
27400 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27410 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
27420 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
27430 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
27440 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27460 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
27470 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
27480 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
27490 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
274a0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
274b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
274c0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
274d0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
274e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
274f0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
27500 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
27510 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
27520 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27530 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
27540 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
27550 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
27560 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
27570 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27580 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
27590 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
275a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
275b0 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
275c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
275d0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
275e0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
275f0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
27600 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
27610 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
27620 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
27630 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
27640 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
27650 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
27660 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
27670 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
27680 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
27690 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
276a0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
276b0 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
276c0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
276d0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
276e0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
276f0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
27700 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
27710 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
27720 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
27730 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
27740 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
27750 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
27760 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
27770 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
27780 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
27790 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
277a0 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
277b0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
277c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
277d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
277e0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
277f0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
27800 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
27810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27820 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
27830 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27840 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
27850 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
27860 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
27870 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
27880 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
27890 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
278a0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
278b0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
278c0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
278d0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
278e0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
278f0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
27900 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27910 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
27920 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
27930 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
27940 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
27950 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
27960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27970 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
27980 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
27990 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
279a0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
279b0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
279c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
279d0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
279e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
279f0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
27a00 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
27a10 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
27a20 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
27a30 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
27a40 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
27a50 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
27a60 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
27a70 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
27a80 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
27a90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27aa0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
27ab0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
27ac0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
27ad0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
27ae0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
27af0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
27b00 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
27b10 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
27b20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
27b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27b40 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
27b50 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
27b60 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27b80 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
27b90 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
27ba0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
27bb0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
27bc0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
27bd0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
27be0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
27bf0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
27c00 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
27c10 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
27c20 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
27c30 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
27c40 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
27c50 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
27c60 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
27c70 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
27c80 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
27c90 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
27ca0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
27cb0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27cc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
27cd0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
27ce0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
27cf0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
27d00 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
27d10 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
27d20 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
27d30 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
27d40 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
27d50 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
27d60 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
27d70 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
27d80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27d90 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
27da0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
27db0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
27dc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
27dd0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
27de0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
27df0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
27e00 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
27e10 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
27e20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27e30 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
27e40 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
27e50 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
27e60 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
27e70 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
27e80 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
27e90 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
27ea0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
27eb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27ec0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
27ed0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
27ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
27ef0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
27f00 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
27f10 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
27f20 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
27f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27f40 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
27f50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
27f60 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
27f70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27f80 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
27f90 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
27fa0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
27fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
27fc0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
27fd0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
27fe0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
27ff0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
28000 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
28010 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
28020 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28030 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
28040 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
28050 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
28060 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
28070 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
28080 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
28090 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
280a0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
280b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
280c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
280d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
280e0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
280f0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
28100 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
28110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
28120 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
28130 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
28140 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28150 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
28160 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
28170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
28180 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
28190 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
281a0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
281b0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
281c0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
281d0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
281e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
281f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
28200 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28210 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
28220 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
28230 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
28240 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
28250 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
28260 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
28270 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
28280 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
28290 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
282a0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
282b0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
282c0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
282d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
282e0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
282f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28300 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
28310 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
28320 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
28330 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
28340 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
28350 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
28360 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
28370 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
28380 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
28390 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
283a0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
283b0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
283c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
283d0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
283e0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
283f0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
28400 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
28410 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
28420 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
28430 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
28440 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
28450 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
28460 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
28470 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
28480 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
28490 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
284a0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
284b0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
284c0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
284d0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
284e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
284f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
28500 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
28510 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
28520 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
28530 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
28540 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
28550 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
28560 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28570 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
28580 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
28590 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
285a0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
285b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
285c0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
285d0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
285e0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
285f0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
28600 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
28610 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
28620 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
28630 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
28640 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
28650 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
28660 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
28670 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
28680 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
28690 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
286a0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
286b0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
286c0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
286d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
286e0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
286f0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
28700 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
28710 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
28720 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
28730 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
28740 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
28750 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
28760 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28770 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
28780 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
28790 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
287a0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
287b0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
287c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
287d0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
287e0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
287f0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
28800 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28810 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
28820 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
28830 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28840 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
28850 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
28860 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
28870 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
28880 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
28890 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
288a0 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
288b0 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
288c0 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
288d0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
288e0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
288f0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
28900 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
28910 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28920 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
28930 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
28940 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
28950 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28960 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
28970 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
28980 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
28990 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
289a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
289b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
289c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
289d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
289e0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
289f0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
28a00 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
28a10 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
28a20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28a30 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
28a40 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
28a50 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
28a60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28a70 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28a80 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
28a90 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
28aa0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
28ab0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
28ac0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
28ad0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
28ae0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
28af0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
28b00 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
28b10 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
28b20 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
28b30 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
28b40 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
28b50 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
28b60 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
28b70 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
28b80 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
28b90 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
28ba0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
28bb0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
28bc0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
28bd0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
28be0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
28bf0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
28c00 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
28c10 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
28c20 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
28c30 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
28c40 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
28c50 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
28c60 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
28c70 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
28c80 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
28c90 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
28ca0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
28cb0 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
28cc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
28cd0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
28ce0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
28cf0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
28d00 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
28d10 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
28d20 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
28d30 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
28d40 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
28d50 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
28d60 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
28d70 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
28d80 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
28d90 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
28da0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
28db0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
28dc0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
28dd0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28de0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
28df0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
28e00 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
28e10 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
28e20 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
28e30 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
28e40 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
28e50 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
28e60 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
28e70 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
28e80 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28e90 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
28ea0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
28eb0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
28ec0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
28ed0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
28ee0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
28ef0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
28f00 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
28f10 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
28f20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
28f30 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
28f40 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
28f50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
28f60 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
28f70 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
28f80 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
28f90 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
28fa0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
28fb0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
28fc0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
28fd0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
28fe0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
28ff0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
29000 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
29010 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
29020 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
29030 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
29040 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
29050 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
29060 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
29070 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
29080 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
29090 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
290a0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
290b0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
290c0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
290d0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
290e0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
290f0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
29100 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
29110 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
29120 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
29130 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
29140 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
29150 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29160 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
29170 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29180 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
29190 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
291a0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
291b0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
291c0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
291d0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
291e0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
291f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
29200 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
29210 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
29220 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
29230 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
29240 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29250 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
29260 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
29270 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
29280 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
29290 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
292a0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
292b0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
292c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
292d0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
292e0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
292f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
29300 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
29310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
29320 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29330 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
29340 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
29350 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
29360 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
29370 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
29380 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
29390 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
293a0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
293b0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
293c0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
293d0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
293e0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
293f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29410 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
29420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29430 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29440 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
29450 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29460 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
29470 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
29480 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
29490 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
294a0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
294b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
294c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
294d0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
294e0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
294f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29500 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
29510 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
29520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29530 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
29540 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
29550 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
29560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
29570 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
29580 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
29590 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
295a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
295b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
295c0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
295d0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
295e0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
295f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29600 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29610 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
29620 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
29630 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
29640 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29650 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
29660 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29670 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29690 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
296a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
296b0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
296c0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
296d0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
296e0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
296f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
29700 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
29710 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
29720 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
29730 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
29740 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
29750 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
29760 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
29770 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
29780 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
29790 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
297a0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
297b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
297c0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
297d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
297e0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
297f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
29800 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
29810 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
29820 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
29830 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
29840 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
29850 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
29860 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
29870 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
29880 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
29890 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
298a0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
298b0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
298c0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
298d0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
298e0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
298f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29900 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29910 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29920 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29930 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
29940 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
29950 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29960 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29970 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
29980 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29990 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
299a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
299b0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
299c0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
299d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
299e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
299f0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
29a00 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
29a10 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
29a20 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
29a30 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
29a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29a50 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
29a60 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
29a70 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
29a80 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
29a90 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
29aa0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
29ab0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
29ac0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
29ad0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
29ae0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
29af0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
29b00 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
29b10 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
29b20 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
29b30 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
29b40 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
29b50 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
29b60 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
29b70 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
29b80 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
29b90 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
29ba0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
29bb0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
29bc0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
29bd0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
29be0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
29bf0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
29c00 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
29c10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
29c20 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
29c30 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
29c40 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
29c50 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
29c60 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
29c70 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
29c80 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
29c90 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
29ca0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
29cb0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
29cc0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
29cd0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
29ce0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
29cf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29d00 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
29d10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29d20 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
29d30 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29d40 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29d50 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
29d60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29d70 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
29d80 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
29d90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29da0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
29db0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29dc0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29dd0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29de0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
29df0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
29e00 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
29e10 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
29e20 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
29e30 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
29e40 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
29e50 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
29e60 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
29e70 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
29e80 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
29e90 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
29ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
29eb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29ec0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
29ed0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
29ee0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
29ef0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
29f00 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
29f10 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
29f20 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
29f30 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
29f40 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
29f50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
29f60 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
29f70 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
29f80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29f90 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29fa0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29fb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29fc0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29fe0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29ff0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a000 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a010 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a020 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a030 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a050 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a060 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2a070 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2a080 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2a090 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2a0a0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2a0b0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2a0c0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2a0d0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2a0e0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2a0f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2a100 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2a110 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2a120 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2a130 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2a140 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2a150 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2a160 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2a170 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2a180 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2a190 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2a1a0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2a1b0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2a1c0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2a1d0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2a1e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2a1f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2a200 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2a210 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a220 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2a230 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2a240 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2a250 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2a260 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2a270 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2a280 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2a290 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2a2a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2a2b0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2a2c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a2d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a2e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a2f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2a300 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2a310 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2a320 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2a330 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2a340 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2a350 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2a360 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2a370 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2a380 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2a390 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2a3a0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2a3b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a3c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2a3d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2a3e0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2a3f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2a400 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2a410 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2a420 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2a430 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2a440 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2a450 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2a460 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a470 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2a480 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2a490 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2a4a0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2a4b0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2a4c0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2a4d0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2a4e0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2a4f0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2a500 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2a510 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2a520 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2a530 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a540 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2a550 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2a560 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2a570 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2a580 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2a590 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2a5a0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2a5b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a5c0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2a5d0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2a5e0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2a5f0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2a600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a610 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2a620 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2a630 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2a640 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2a650 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2a660 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2a670 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2a680 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2a690 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2a6a0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2a6b0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2a6c0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2a6d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2a6e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a6f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2a700 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2a710 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2a720 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2a730 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2a740 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2a750 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2a760 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2a770 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2a780 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2a790 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2a7a0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2a7b0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2a7c0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2a7d0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2a7e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2a800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a810 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2a820 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2a830 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2a840 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2a850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a860 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2a870 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2a880 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2a890 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2a8a0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2a8b0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2a8c0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2a8d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2a8e0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2a8f0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2a900 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2a910 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2a920 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2a930 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2a940 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2a950 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2a960 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2a970 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2a980 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2a990 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2a9a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a9b0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2a9c0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2a9d0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2a9e0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2a9f0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2aa00 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2aa10 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2aa20 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2aa30 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2aa40 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2aa50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2aa60 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2aa70 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2aa80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2aa90 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2aaa0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2aab0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2aac0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2aad0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2aae0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2aaf0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2ab00 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2ab10 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2ab20 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2ab30 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2ab40 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2ab50 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2ab60 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2ab70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2ab80 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2ab90 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2aba0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2abb0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2abc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2abd0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2abe0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2abf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2ac00 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2ac10 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2ac20 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2ac30 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2ac40 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2ac50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2ac60 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2ac70 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2ac80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2ac90 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2aca0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2acb0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2acc0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2acd0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2ace0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2acf0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2ad00 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2ad10 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2ad20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2ad30 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2ad40 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2ad50 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2ad60 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2ad70 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2ad80 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2ad90 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2ada0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2adb0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2adc0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2add0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2ade0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2adf0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2ae00 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2ae10 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2ae20 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2ae30 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2ae40 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2ae50 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2ae60 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2ae70 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2ae80 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2ae90 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2aea0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2aeb0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2aec0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2aed0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2aee0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2aef0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2af00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2af10 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2af20 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2af30 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2af40 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2af50 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2af60 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2af70 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2af80 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2af90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2afa0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2afb0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2afc0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2afd0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2afe0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2aff0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2b000 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2b010 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b020 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2b030 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2b040 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2b050 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2b060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b070 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2b080 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2b090 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2b0a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2b0b0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2b0c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b0d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2b0e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b0f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2b100 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b110 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2b120 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b130 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2b140 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b150 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2b160 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b170 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2b190 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2b1a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2b1b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b1c0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2b1d0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b1e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2b1f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b200 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2b210 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b220 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b230 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2b240 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2b250 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2b260 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2b270 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2b280 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2b290 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2b2a0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2b2b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2b2c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2b2d0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2b2e0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2b2f0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2b300 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2b310 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2b320 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2b330 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2b340 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2b350 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2b360 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2b370 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2b380 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2b390 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2b3a0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b3b0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2b3c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2b3d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2b3e0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b3f0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2b400 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2b410 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2b420 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2b430 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2b440 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2b450 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2b460 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2b470 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2b480 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2b490 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2b4a0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2b4b0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2b4c0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2b4d0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2b4e0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2b4f0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2b500 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2b510 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b520 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2b530 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2b540 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2b550 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2b560 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2b570 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2b580 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2b590 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2b5a0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2b5b0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2b5c0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2b5d0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2b5e0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2b5f0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2b600 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2b610 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2b620 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2b630 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2b640 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2b650 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2b660 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2b670 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2b680 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2b690 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2b6a0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2b6b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2b6c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b6d0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2b6e0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2b6f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2b700 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2b710 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b720 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2b730 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2b740 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2b750 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2b760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b770 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2b780 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2b790 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2b7a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b7b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b7c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2b7d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2b7e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2b7f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2b800 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2b810 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2b820 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2b830 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2b840 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2b850 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2b860 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2b870 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2b880 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2b890 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2b8a0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2b8b0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2b8c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2b8d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2b8e0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2b8f0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2b900 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b910 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2b920 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2b930 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2b940 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2b950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b960 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b970 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2b980 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2b990 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2b9a0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2b9b0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2b9c0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2b9d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2b9e0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2b9f0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2ba00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2ba10 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2ba20 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2ba30 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2ba40 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2ba50 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2ba60 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2ba70 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2ba80 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2ba90 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2baa0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2bab0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2bac0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2bad0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2bae0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2baf0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2bb00 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2bb10 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2bb20 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2bb30 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2bb40 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2bb50 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2bb60 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2bb70 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2bb80 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2bb90 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2bba0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2bbb0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2bbc0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2bbd0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2bbe0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2bbf0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2bc00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2bc10 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2bc20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2bc30 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2bc40 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2bc50 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2bc60 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2bc70 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2bc80 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2bc90 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2bca0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2bcb0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2bcc0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2bcd0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2bce0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2bcf0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2bd00 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2bd10 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2bd20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2bd30 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2bd40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bd50 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2bd60 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2bd70 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2bd80 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2bd90 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2bda0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2bdb0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2bdc0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2bdd0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2bde0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2bdf0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2be00 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2be10 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2be20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2be30 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2be40 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2be50 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2be60 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2be70 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2be80 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2be90 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2bea0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2beb0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2bec0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2bed0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2bee0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2bef0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2bf00 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2bf10 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2bf20 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2bf30 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2bf40 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2bf50 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2bf60 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2bf70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2bf80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2bf90 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2bfa0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2bfb0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2bfc0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2bfd0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2bfe0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2bff0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2c000 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2c010 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2c020 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2c030 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2c040 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2c050 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c060 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2c070 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2c080 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2c090 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2c0a0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2c0b0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2c0c0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2c0d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2c0e0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2c0f0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2c100 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2c110 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2c120 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2c130 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2c140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2c150 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2c160 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2c170 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2c180 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2c190 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2c1a0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2c1b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2c1c0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2c1d0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2c1e0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2c1f0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2c200 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c210 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2c220 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2c230 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2c240 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2c250 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2c260 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2c270 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2c280 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2c290 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2c2a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c2b0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2c2c0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2c2d0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2c2e0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2c2f0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2c300 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2c310 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2c320 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2c330 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2c340 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2c350 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c360 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2c370 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2c380 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2c390 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2c3a0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2c3b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2c3c0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2c3d0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2c3e0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2c3f0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2c400 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2c410 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2c420 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2c430 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2c440 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2c450 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2c460 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2c470 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2c480 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2c490 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2c4a0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2c4b0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2c4c0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2c4d0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2c4e0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2c4f0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2c500 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2c510 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2c520 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2c530 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2c540 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2c550 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2c560 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2c570 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2c580 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2c590 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2c5a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2c5b0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2c5c0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2c5d0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2c5e0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2c5f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2c600 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2c610 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2c620 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2c630 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2c640 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2c650 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2c660 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2c670 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2c680 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2c690 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2c6a0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2c6b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2c6c0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2c6d0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2c6e0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2c6f0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2c700 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2c710 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2c720 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2c730 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2c740 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2c750 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c760 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2c770 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2c780 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2c790 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2c7a0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2c7b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c7c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2c7d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2c7e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2c7f0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2c800 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2c810 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2c820 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2c830 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c840 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2c850 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2c860 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2c870 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2c880 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2c890 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2c8a0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2c8b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c8c0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2c8d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c8e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2c8f0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2c900 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2c910 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2c920 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c930 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2c940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c950 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2c960 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2c970 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2c980 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2c990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2c9a0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2c9b0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2c9c0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2c9d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c9e0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2c9f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2ca00 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2ca10 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2ca20 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2ca30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2ca40 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2ca50 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2ca60 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2ca70 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2ca80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2ca90 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2caa0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2cab0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2cac0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2cad0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2cae0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2caf0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2cb00 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2cb10 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2cb20 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2cb30 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2cb40 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2cb50 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2cb60 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2cb70 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2cb80 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2cb90 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2cba0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2cbb0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2cbc0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2cbd0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2cbe0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2cbf0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2cc00 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2cc10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2cc20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2cc30 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2cc40 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2cc50 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2cc60 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2cc70 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2cc80 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2cc90 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2cca0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2ccb0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2ccc0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2ccd0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2cce0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2ccf0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2cd00 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2cd10 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2cd20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2cd30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2cd40 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2cd50 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2cd60 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2cd70 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2cd80 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2cd90 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2cda0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2cdb0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2cdc0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2cdd0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2cde0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2cdf0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2ce00 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2ce10 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2ce20 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2ce30 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2ce40 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2ce50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2ce60 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2ce70 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2ce80 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2ce90 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2cea0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2ceb0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2cec0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2ced0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2cee0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2cef0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2cf00 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2cf10 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2cf20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cf30 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2cf40 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2cf50 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2cf60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2cf70 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2cf80 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2cf90 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2cfa0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2cfb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2cfc0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2cfd0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2cfe0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2cff0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2d000 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2d010 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2d020 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d030 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2d040 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2d050 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d060 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2d070 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2d080 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2d090 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d0a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d0b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d0c0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2d0d0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2d0e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d0f0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d100 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2d110 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2d120 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2d130 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2d140 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2d150 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d160 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2d170 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2d180 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2d190 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2d1a0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2d1b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d1c0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2d1d0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2d1e0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2d1f0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2d200 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2d210 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2d220 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2d230 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2d240 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d250 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2d260 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2d270 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2d280 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d290 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d2a0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d2b0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d2c0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2d2d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2d2e0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2d2f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d300 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d310 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2d320 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2d330 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2d340 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2d350 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2d370 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2d380 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2d390 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2d3a0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2d3b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d3c0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2d3d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d3e0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2d3f0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d400 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d410 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d420 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2d430 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2d440 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2d450 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2d460 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2d470 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2d480 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2d490 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d4a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d4b0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2d4c0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2d4d0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2d4e0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2d4f0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2d500 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2d510 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2d520 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2d530 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2d540 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2d550 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2d560 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2d570 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2d580 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2d590 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2d5a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2d5b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d5c0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2d5d0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2d5e0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2d5f0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2d600 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2d610 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2d620 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2d630 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2d640 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d650 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2d660 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2d670 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2d680 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2d690 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2d6a0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2d6b0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2d6c0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2d6d0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2d6e0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d6f0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2d700 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2d710 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2d720 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2d730 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2d740 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d750 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2d760 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2d770 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d780 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2d790 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d7a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2d7b0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2d7c0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2d7d0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2d7e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d7f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d800 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2d810 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2d820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d830 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2d840 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2d850 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2d860 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2d870 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2d880 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2d890 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2d8a0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2d8b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d8c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2d8d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d8e0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2d8f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2d900 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2d910 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2d920 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2d930 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d940 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2d950 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2d960 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2d970 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2d980 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d990 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2d9a0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2d9b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d9c0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2d9d0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2d9e0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2d9f0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2da00 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2da10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2da20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2da30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2da40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2da50 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2da60 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2da70 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2da80 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2da90 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2daa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2dab0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2dac0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2dad0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2dae0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2daf0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2db00 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2db10 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2db20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2db30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2db40 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2db50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2db60 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2db70 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2db80 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2db90 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2dba0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2dbb0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2dbc0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2dbd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2dbe0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2dbf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dc00 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2dc10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2dc20 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2dc30 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2dc40 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2dc50 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2dc60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2dc70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dc80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2dc90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2dca0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2dcb0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2dcc0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2dcd0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2dce0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2dcf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2dd00 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2dd10 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2dd20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2dd30 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2dd40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2dd50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2dd60 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2dd70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2dd80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2dd90 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2dda0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2ddb0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2ddc0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2ddd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2dde0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2ddf0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2de00 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2de10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2de20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2de30 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2de40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2de50 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2de60 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2de70 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2de80 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2de90 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2dea0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2deb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2dec0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2ded0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2dee0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2def0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2df00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2df10 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2df20 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2df30 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2df40 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2df50 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2df60 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2df70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2df80 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2df90 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2dfa0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2dfb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2dfc0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2dfd0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2dfe0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2dff0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2e000 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2e010 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2e020 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2e030 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2e040 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2e050 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2e060 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2e070 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2e080 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2e090 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2e0a0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2e0b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e0c0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2e0d0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2e0e0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2e0f0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e100 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2e110 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2e120 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e130 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e140 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e150 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2e160 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2e170 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2e180 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2e190 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e1a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2e1b0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2e1c0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2e1d0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2e1e0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2e1f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2e200 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2e210 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2e220 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2e230 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2e240 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2e250 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2e260 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2e270 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2e280 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2e290 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2e2a0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2e2b0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e2c0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e2d0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2e2e0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2e2f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e300 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2e310 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2e320 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2e330 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e340 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e350 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2e360 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2e370 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2e380 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2e390 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2e3a0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2e3b0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e3c0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2e3d0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e3e0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e3f0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e400 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2e410 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e420 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e430 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2e440 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2e450 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2e460 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2e470 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2e480 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2e490 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2e4a0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2e4b0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2e4c0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2e4d0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2e4e0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2e4f0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2e500 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2e510 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2e520 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2e530 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2e540 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2e550 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2e560 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2e570 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2e580 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2e590 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2e5a0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2e5b0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2e5c0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2e5d0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2e5e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2e5f0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2e600 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2e610 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2e620 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2e630 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e640 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2e650 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2e660 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2e670 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e680 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2e690 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2e6a0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2e6b0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2e6c0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2e6d0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2e6e0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2e6f0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2e700 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2e710 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2e720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e730 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2e740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e750 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2e760 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2e770 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2e780 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2e790 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2e7a0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2e7b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e7c0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2e7d0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2e7e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e7f0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2e800 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e810 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2e820 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2e830 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2e840 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2e850 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2e860 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2e870 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2e880 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e890 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2e8a0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2e8b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2e8c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2e8d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2e8e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2e8f0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2e900 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2e910 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2e920 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2e930 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2e940 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2e950 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2e960 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2e970 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2e980 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2e990 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2e9a0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2e9b0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2e9c0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2e9d0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2e9e0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2e9f0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2ea00 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2ea10 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2ea20 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2ea30 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2ea40 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2ea50 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2ea60 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2ea70 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2ea80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2ea90 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2eaa0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2eab0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2eac0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2ead0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2eae0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2eaf0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2eb00 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2eb10 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2eb20 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2eb30 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2eb40 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2eb50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2eb60 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2eb70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2eb80 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2eb90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2eba0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2ebb0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ebc0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2ebd0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2ebe0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2ebf0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2ec00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ec10 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2ec20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2ec30 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2ec40 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2ec50 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2ec60 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2ec70 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2ec80 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2ec90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2eca0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2ecb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ecc0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2ecd0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2ece0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2ecf0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2ed00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ed10 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2ed20 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2ed30 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2ed40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ed50 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2ed60 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2ed70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ed80 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2ed90 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2eda0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2edb0 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2edc0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2edd0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2ede0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2edf0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2ee00 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2ee10 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2ee20 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2ee30 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2ee40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ee50 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2ee60 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2ee70 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2ee80 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2ee90 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2eea0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2eeb0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2eec0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2eed0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2eee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eef0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2ef00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2ef10 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2ef20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2ef30 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2ef40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2ef50 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2ef60 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2ef70 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2ef80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2ef90 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2efa0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2efb0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2efc0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2efd0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2efe0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2eff0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2f000 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2f010 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2f020 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2f030 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2f040 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2f050 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2f060 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f070 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2f080 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f090 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2f0a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f0c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2f0d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f0e0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2f0f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2f100 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2f110 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2f120 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f130 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2f140 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2f150 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f160 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2f170 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2f180 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2f190 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f1a0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2f1b0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2f1c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2f1d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f1e0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2f1f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2f200 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2f210 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f230 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2f240 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f250 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2f260 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2f270 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2f280 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f290 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f2a0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2f2b0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f2c0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2f2d0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2f2e0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2f2f0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2f300 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2f310 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2f320 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f330 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2f340 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2f350 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2f360 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2f370 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2f380 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2f390 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2f3a0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2f3b0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2f3c0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2f3d0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2f3e0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2f3f0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2f400 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f410 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2f420 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2f430 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2f440 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2f450 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2f460 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2f470 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2f480 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2f490 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2f4a0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2f4b0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2f4c0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2f4d0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2f4e0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2f4f0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2f500 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2f510 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2f520 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2f530 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2f540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f550 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2f560 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2f570 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2f580 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2f590 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2f5a0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2f5b0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2f5c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2f5d0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2f5e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2f5f0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2f600 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2f610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f620 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2f630 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2f640 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2f650 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2f660 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f670 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2f680 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2f690 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2f6a0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2f6b0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2f6c0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2f6d0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2f6e0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2f6f0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2f700 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2f710 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2f720 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2f730 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2f740 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2f750 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2f760 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2f770 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2f780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f790 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2f7a0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2f7b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f7c0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2f7d0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2f7e0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2f7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2f800 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2f810 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2f820 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2f830 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2f840 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2f850 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2f860 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2f870 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2f880 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2f890 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2f8a0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2f8b0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2f8c0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2f8d0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2f8e0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2f8f0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2f900 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2f910 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2f920 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2f930 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f940 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2f950 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2f960 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2f970 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f980 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2f990 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2f9a0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2f9b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f9c0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2f9d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2f9e0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2f9f0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2fa00 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2fa10 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2fa20 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2fa30 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2fa40 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2fa50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2fa60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2fa70 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2fa80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2fa90 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2faa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fab0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2fac0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2fad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2fae0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2faf0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2fb00 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2fb10 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2fb20 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2fb30 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2fb40 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
2fb50 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2fb60 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2fb70 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2fb80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2fb90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fba0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2fbb0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2fbc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2fbd0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2fbe0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2fbf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2fc00 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2fc10 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2fc20 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2fc30 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fc40 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2fc50 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2fc60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fc70 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2fc80 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2fc90 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2fca0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2fcb0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2fcc0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2fcd0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2fce0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2fcf0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2fd00 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2fd10 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2fd20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2fd30 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2fd40 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2fd50 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2fd60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2fd70 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2fd80 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2fd90 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2fda0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2fdb0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2fdc0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2fdd0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2fde0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2fdf0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2fe00 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2fe10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2fe20 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2fe30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
2fe40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2fe50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fe60 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2fe70 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2fe80 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2fe90 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
2fea0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
2feb0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
2fec0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2fed0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
2fee0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fef0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2ff00 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
2ff10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ff20 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
2ff30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2ff40 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2ff50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2ff60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2ff70 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2ff80 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
2ff90 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2ffa0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2ffb0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
2ffc0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
2ffd0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
2ffe0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
2fff0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
30000 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
30010 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
30020 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
30030 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30040 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30050 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30060 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30070 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30080 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30090 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
300a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
300b0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
300c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
300d0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
300e0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
300f0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
30100 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
30110 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
30120 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
30130 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
30140 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
30150 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30160 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
30170 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
30180 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
30190 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
301a0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
301b0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
301c0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
301d0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
301e0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
301f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
30200 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
30210 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
30220 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
30230 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
30240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
30250 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
30260 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
30270 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
30280 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
30290 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
302a0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
302b0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
302c0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
302d0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
302e0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
302f0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
30300 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
30310 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
30320 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
30330 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
30340 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
30350 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
30360 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
30370 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
30380 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
30390 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
303a0 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
303b0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
303c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
303d0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
303e0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
303f0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
30400 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
30410 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
30420 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
30430 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
30440 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
30450 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
30460 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30470 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
30480 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
30490 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
304a0 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
304b0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
304c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
304d0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
304e0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
304f0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
30500 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
30510 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
30520 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
30530 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
30540 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
30550 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30560 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
30570 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
30580 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
30590 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
305a0 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
305b0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
305c0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
305d0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
305e0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
305f0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
30600 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
30610 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
30620 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
30630 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
30640 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
30650 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30660 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
30670 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
30680 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
30690 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
306a0 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
306b0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
306c0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
306d0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
306e0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
306f0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
30700 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
30710 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
30720 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
30730 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
30740 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
30750 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
30760 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
30770 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
30780 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30790 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
307a0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
307b0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
307c0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
307d0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
307e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
307f0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
30800 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
30810 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
30820 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
30830 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
30840 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
30850 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
30860 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
30870 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30880 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
30890 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
308a0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
308b0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
308c0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
308d0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
308e0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
308f0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
30900 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
30910 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
30920 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
30930 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
30940 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30950 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
30960 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
30970 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
30980 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
30990 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
309a0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
309b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
309c0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
309d0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
309e0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
309f0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
30a00 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
30a10 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
30a20 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
30a30 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
30a40 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
30a50 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
30a60 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
30a70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
30a80 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
30a90 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
30aa0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
30ab0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
30ac0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
30ad0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
30ae0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
30af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30b00 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
30b10 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
30b20 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
30b30 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
30b40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30b50 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
30b60 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
30b70 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
30b80 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
30b90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
30ba0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
30bb0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
30bc0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
30bd0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
30be0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30bf0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
30c00 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
30c10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
30c20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30c30 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
30c40 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
30c50 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
30c60 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
30c70 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
30c80 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
30c90 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
30ca0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
30cb0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
30cc0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
30cd0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
30ce0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
30cf0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
30d00 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
30d10 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
30d20 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
30d30 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
30d40 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
30d50 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
30d60 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
30d70 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
30d80 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
30d90 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
30da0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
30db0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
30dc0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30dd0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30de0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
30df0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
30e00 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30e10 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
30e20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
30e30 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
30e40 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
30e50 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
30e60 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
30e70 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
30e80 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
30e90 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
30ea0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
30eb0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
30ec0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
30ed0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
30ee0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
30ef0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
30f00 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
30f10 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
30f20 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
30f30 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
30f40 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
30f50 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
30f60 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
30f70 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
30f80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
30f90 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
30fa0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30fb0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
30fc0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
30fd0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
30fe0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
30ff0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
31000 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
31010 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31020 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
31030 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
31040 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
31050 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
31060 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31070 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
31080 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31090 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
310a0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
310b0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
310c0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
310d0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
310e0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
310f0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
31100 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31110 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31120 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31130 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
31140 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31150 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31160 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
31170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31180 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31190 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
311a0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
311b0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
311c0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
311d0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
311e0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
311f0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31200 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31210 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31220 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31230 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31250 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31260 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31270 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31280 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
31290 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
312a0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
312b0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
312c0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
312d0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
312e0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
312f0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
31300 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
31310 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31320 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31330 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31340 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31350 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31360 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31370 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31380 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31390 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
313a0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
313b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
313c0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
313d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
313e0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
313f0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
31400 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
31410 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
31420 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
31430 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
31440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31450 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
31460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31470 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
31480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31490 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
314a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
314b0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
314c0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
314d0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
314e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
314f0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
31500 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
31510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31520 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
31530 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
31540 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31550 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
31560 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
31570 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
31580 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
31590 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
315a0 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
315b0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
315c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
315d0 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
315e0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
315f0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
31600 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31610 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
31620 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31630 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
31640 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31650 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
31660 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
31670 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
31680 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
31690 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
316a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
316b0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
316c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
316d0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
316e0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
316f0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
31700 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
31710 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
31720 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
31730 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
31740 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
31750 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
31760 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31770 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
31780 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31790 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
317a0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
317b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
317c0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
317d0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
317e0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
317f0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
31800 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
31810 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
31820 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31830 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
31840 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
31850 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31860 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31870 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
31880 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
31890 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
318a0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
318b0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
318c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
318d0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
318e0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
318f0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
31900 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
31910 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
31920 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
31930 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
31940 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
31950 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31960 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
31970 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
31980 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
31990 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
319a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
319b0 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
319c0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
319d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
319e0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
319f0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
31a00 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
31a10 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
31a20 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
31a30 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31a40 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
31a50 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
31a60 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
31a70 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
31a80 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
31a90 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
31aa0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
31ab0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
31ac0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
31ad0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
31ae0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
31af0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
31b00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
31b10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
31b20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31b30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31b40 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
31b50 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
31b60 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31b70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31b80 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
31b90 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
31ba0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
31bb0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
31bc0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
31bd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31be0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
31bf0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
31c00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31c10 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
31c20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31c30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
31c40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31c50 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
31c60 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
31c70 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
31c80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
31c90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31ca0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
31cb0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
31cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31cd0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
31ce0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
31cf0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
31d00 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
31d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
31d20 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
31d30 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31d40 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
31d50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31d60 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
31d70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
31d80 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31d90 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
31da0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
31db0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
31dc0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
31dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31de0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
31df0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
31e00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
31e10 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
31e20 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
31e30 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
31e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31e50 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
31e60 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
31e70 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
31e80 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
31e90 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
31ea0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
31eb0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
31ec0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
31ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31ee0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
31ef0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
31f00 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
31f10 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
31f20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
31f30 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
31f40 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
31f50 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
31f60 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
31f70 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
31f80 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
31f90 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
31fa0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
31fb0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
31fc0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
31fd0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
31fe0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
31ff0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
32000 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
32010 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
32020 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
32030 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
32040 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
32050 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
32060 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
32070 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
32080 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
32090 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
320a0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
320b0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
320c0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
320d0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
320e0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
320f0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
32100 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
32110 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
32120 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
32130 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
32140 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
32150 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
32160 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
32170 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
32180 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32190 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
321a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
321b0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
321c0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
321d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
321e0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
321f0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
32200 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
32210 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
32220 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32230 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32240 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
32250 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32260 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
32270 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32280 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
32290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
322a0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
322b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
322c0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
322d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
322e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
322f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32300 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
32310 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
32320 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32330 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32340 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
32350 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
32360 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
32370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32380 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32390 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
323a0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
323b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
323c0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
323d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
323e0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
323f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32400 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
32410 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
32420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32430 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
32440 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
32450 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32460 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32470 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
32480 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
32490 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
324a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
324b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
324c0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
324d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
324e0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
324f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32500 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
32510 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
32520 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
32530 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
32540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32550 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
32560 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
32570 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
32580 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
32590 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
325a0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
325b0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
325c0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
325d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
325e0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
325f0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
32600 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
32610 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
32620 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
32630 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
32640 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
32650 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
32660 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32670 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
32680 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
32690 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
326a0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
326b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
326c0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
326d0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
326e0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
326f0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
32700 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
32710 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
32720 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
32730 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
32740 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
32750 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
32760 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
32770 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
32780 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
32790 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
327a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
327b0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
327c0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
327d0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
327e0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
327f0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
32800 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
32810 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
32820 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
32830 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
32840 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
32850 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
32860 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
32870 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32880 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
32890 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
328a0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
328b0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
328c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
328d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
328e0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
328f0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
32900 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
32910 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
32920 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
32930 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
32940 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
32950 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
32960 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
32970 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
32980 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
32990 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
329a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
329b0 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
329c0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
329d0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
329e0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
329f0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
32a00 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
32a10 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32a20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
32a30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
32a40 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
32a50 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32a60 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
32a70 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
32a80 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
32a90 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
32aa0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
32ab0 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
32ac0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
32ad0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
32ae0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32af0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
32b00 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
32b10 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
32b20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
32b30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
32b40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
32b50 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
32b60 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
32b70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32b80 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
32b90 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
32ba0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
32bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
32bc0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
32bd0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
32be0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
32bf0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
32c00 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
32c10 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
32c20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
32c30 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
32c40 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
32c50 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
32c60 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
32c70 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
32c80 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32c90 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
32ca0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
32cb0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
32cc0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
32cd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
32ce0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
32cf0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
32d00 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
32d10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32d20 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
32d30 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
32d40 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
32d50 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32d60 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32d70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32d80 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
32d90 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
32da0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
32db0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
32dc0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
32dd0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
32de0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32df0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
32e00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32e10 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
32e20 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
32e30 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32e40 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32e50 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32e60 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32e70 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32e80 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32e90 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32ea0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
32eb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32ec0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
32ed0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
32ee0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32ef0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32f00 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32f10 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
32f20 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
32f30 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32f40 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
32f50 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
32f60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32f70 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
32f80 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
32f90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32fa0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
32fb0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32fc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32fd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32fe0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32ff0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33000 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
33010 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
33020 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33030 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33040 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33050 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
33060 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
33070 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
33080 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33090 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
330a0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
330b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
330c0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
330d0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
330e0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
330f0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
33100 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
33110 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
33120 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
33130 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
33140 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
33150 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33160 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
33170 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
33180 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
33190 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
331a0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
331b0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
331c0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
331d0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
331e0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
331f0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
33200 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
33210 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
33220 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
33230 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
33240 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
33250 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33260 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
33270 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
33280 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
33290 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
332a0 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
332b0 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
332c0 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
332d0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
332e0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
332f0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
33300 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
33310 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
33320 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33330 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33340 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
33350 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33360 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33370 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
33380 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
33390 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
333a0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
333b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
333c0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
333d0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
333e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
333f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
33400 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
33410 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
33420 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33430 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33440 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
33450 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
33460 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
33470 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
33480 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
33490 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
334a0 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
334b0 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
334c0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
334d0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
334e0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
334f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33500 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
33510 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
33520 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33530 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
33540 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
33550 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
33560 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33570 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
33580 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
33590 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
335a0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
335b0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
335c0 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
335d0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
335e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
335f0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
33600 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
33610 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
33620 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
33630 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
33640 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
33650 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
33660 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
33670 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
33680 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
33690 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
336a0 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
336b0 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
336c0 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
336d0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
336e0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
336f0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
33700 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
33710 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
33720 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33730 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33740 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
33750 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
33760 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
33770 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
33780 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33790 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
337a0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
337b0 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
337c0 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
337d0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
337e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
337f0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
33800 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
33810 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
33820 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
33830 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
33840 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
33850 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
33860 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
33870 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33880 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
33890 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
338a0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
338b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
338c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
338d0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
338e0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
338f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
33900 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
33910 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
33920 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
33930 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33940 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
33950 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
33960 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
33970 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
33980 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
33990 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
339a0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
339b0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
339c0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
339d0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
339e0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
339f0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
33a00 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
33a10 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
33a20 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
33a30 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
33a40 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
33a50 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
33a60 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
33a70 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
33a80 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
33a90 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
33aa0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33ab0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33ac0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
33ad0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
33ae0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
33af0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33b00 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
33b10 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
33b20 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
33b30 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
33b40 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
33b50 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
33b60 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
33b70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
33b80 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
33b90 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
33ba0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
33bb0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
33bc0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
33bd0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
33be0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
33bf0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
33c00 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
33c10 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
33c20 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
33c30 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
33c40 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
33c50 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
33c60 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
33c70 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
33c80 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
33c90 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
33ca0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
33cb0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
33cc0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
33cd0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
33ce0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
33cf0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33d00 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
33d10 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
33d20 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
33d30 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33d40 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
33d50 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
33d60 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
33d70 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33d80 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
33d90 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
33da0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
33db0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
33dc0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
33dd0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
33de0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
33df0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
33e00 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
33e10 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
33e20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
33e30 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33e40 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33e50 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33e60 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33e70 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33e80 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
33e90 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
33ea0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
33eb0 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
33ec0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
33ed0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
33ee0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
33ef0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
33f00 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
33f10 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
33f20 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
33f30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33f40 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33f50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33f60 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
33f70 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33f80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
33f90 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
33fa0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
33fb0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
33fc0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
33fd0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
33fe0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
33ff0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
34000 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
34010 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
34020 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
34030 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
34040 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
34050 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
34060 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
34070 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34080 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
34090 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
340a0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
340b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
340c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
340d0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
340e0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
340f0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
34100 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
34110 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
34120 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
34130 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
34140 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
34150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34160 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
34170 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
34180 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
34190 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
341a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
341b0 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
341c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
341d0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
341e0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
341f0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
34200 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
34210 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
34220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34230 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
34240 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34250 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34260 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34270 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34280 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
34290 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
342a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
342b0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
342c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
342d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
342e0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
342f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34300 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
34310 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
34320 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
34330 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
34340 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
34350 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
34360 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
34370 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
34380 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
34390 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
343a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
343b0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
343c0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
343d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
343e0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
343f0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
34400 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
34410 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
34420 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
34430 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
34440 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34450 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
34460 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34470 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
34480 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
34490 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
344a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
344b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
344c0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
344d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
344e0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
344f0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
34500 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
34510 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
34520 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
34530 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34540 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34550 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34560 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34570 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34580 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
34590 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
345a0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
345b0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
345c0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
345d0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
345e0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
345f0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
34600 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
34610 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
34620 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34630 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
34640 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34650 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
34660 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
34670 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
34680 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
34690 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
346a0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
346b0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
346c0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
346d0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
346e0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
346f0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
34700 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
34710 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34720 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
34730 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
34740 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
34750 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
34760 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
34770 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
34780 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
34790 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
347a0 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
347b0 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
347c0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
347d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
347e0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
347f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34800 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
34810 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
34820 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
34830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34840 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
34850 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
34860 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34870 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34880 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34890 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
348a0 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
348b0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
348c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
348d0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
348e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
348f0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34900 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34910 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34920 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
34930 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
34940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34950 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
34960 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34970 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34980 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34990 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
349a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
349b0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
349c0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
349d0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
349e0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
349f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34a00 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
34a10 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34a20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
34a30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34a40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34a50 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
34a60 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34a70 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34a80 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
34a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34aa0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
34ab0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34ac0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34ad0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
34ae0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34af0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
34b00 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
34b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34b20 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34b30 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
34b40 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34b50 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
34b60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34b70 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
34b80 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
34b90 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34ba0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34bb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34bc0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
34bd0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
34be0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
34bf0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
34c00 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34c10 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34c20 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34c30 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
34c40 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34c50 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
34c60 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
34c70 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
34c80 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
34c90 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
34ca0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
34cb0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34cc0 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
34cd0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
34ce0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34cf0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34d00 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
34d10 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
34d20 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
34d30 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34d40 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34d50 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34d60 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34d70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
34d80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34d90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34da0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34db0 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
34dc0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
34dd0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
34de0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
34df0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
34e00 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
34e10 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
34e20 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
34e30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
34e40 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
34e50 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
34e60 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
34e70 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
34e80 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
34e90 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
34ea0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
34eb0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
34ec0 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
34ed0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
34ee0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
34ef0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
34f00 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
34f10 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
34f20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
34f30 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
34f40 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
34f50 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
34f60 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
34f70 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
34f80 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
34f90 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
34fa0 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
34fb0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
34fc0 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
34fd0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
34fe0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
34ff0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
35000 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
35010 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
35020 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
35030 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
35040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35050 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
35060 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
35070 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
35080 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
35090 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
350a0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
350b0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
350c0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
350d0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
350e0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
350f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35100 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35110 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35120 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
35130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35140 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
35150 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
35160 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
35170 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
35180 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
35190 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
351a0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
351b0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
351c0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
351d0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
351e0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
351f0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
35200 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
35210 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
35220 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
35230 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
35240 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35250 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35260 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35270 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
35280 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35290 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
352a0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
352b0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
352c0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
352d0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
352e0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
352f0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
35300 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
35310 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
35320 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
35330 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35340 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35350 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
35360 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
35370 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35380 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35390 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
353a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
353b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
353c0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
353d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
353e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
353f0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
35400 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
35410 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35420 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
35430 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
35440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
35450 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
35460 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
35470 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
35480 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
35490 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
354a0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
354b0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
354c0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
354d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
354e0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
354f0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
35500 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
35510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35520 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
35530 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
35540 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
35550 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
35560 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
35570 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
35580 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
35590 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
355a0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
355b0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
355c0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
355d0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
355e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
355f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35600 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
35610 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
35620 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
35630 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35640 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
35650 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35660 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
35670 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35680 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
35690 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
356a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
356b0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
356c0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
356d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
356e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
356f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35700 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
35710 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35720 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
35730 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35740 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
35750 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35760 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
35770 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
35780 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
35790 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
357a0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
357b0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
357c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
357d0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
357e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
357f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35800 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
35810 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
35820 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35830 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
35840 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
35850 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
35860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35870 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
35880 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
35890 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
358a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
358b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
358c0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
358d0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
358e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
358f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35900 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35910 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35920 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35930 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35940 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35950 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35960 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35970 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35980 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35990 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
359a0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
359b0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
359c0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
359d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
359e0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
359f0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
35a00 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
35a10 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35a20 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
35a30 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
35a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
35a50 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
35a60 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
35a70 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
35a80 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
35a90 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
35aa0 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
35ab0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
35ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35ad0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
35ae0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35af0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
35b00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
35b10 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
35b20 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
35b30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35b40 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
35b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35b60 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
35b70 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
35b80 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
35b90 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
35ba0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35bb0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
35bc0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
35bd0 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
35be0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
35bf0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
35c00 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
35c10 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
35c20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
35c30 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
35c40 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
35c50 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
35c60 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
35c70 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
35c80 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
35c90 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35ca0 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
35cb0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35cc0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
35cd0 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
35ce0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35cf0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
35d00 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
35d10 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
35d20 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
35d30 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
35d40 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
35d50 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35d60 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35d70 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
35d80 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
35d90 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
35da0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
35db0 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
35dc0 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
35dd0 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
35de0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
35df0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
35e00 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
35e10 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
35e20 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
35e30 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
35e40 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
35e50 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
35e60 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35e70 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
35e80 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
35e90 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
35ea0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
35eb0 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
35ec0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35ed0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35ee0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35ef0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
35f00 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
35f10 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
35f20 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
35f30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35f40 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
35f50 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35f60 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
35f70 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
35f80 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
35f90 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
35fa0 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
35fb0 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
35fc0 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
35fd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
35fe0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
35ff0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
36000 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
36010 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
36020 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
36030 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
36040 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36050 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
36060 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
36070 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
36080 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
36090 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
360a0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
360b0 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
360c0 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
360d0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
360e0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
360f0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
36100 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
36110 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
36120 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
36130 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
36140 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
36150 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
36160 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
36170 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
36180 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36190 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
361a0 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
361b0 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
361c0 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
361d0 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
361e0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
361f0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
36200 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
36210 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
36220 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
36230 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36240 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
36250 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
36260 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
36270 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
36280 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
36290 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
362a0 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
362b0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
362c0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
362d0 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
362e0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
362f0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
36300 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
36310 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
36320 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
36330 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
36340 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
36350 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36360 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
36370 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
36380 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
36390 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
363a0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
363b0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
363c0 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
363d0 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
363e0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
363f0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
36400 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
36410 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
36420 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
36430 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
36440 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
36450 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
36460 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
36470 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
36480 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
36490 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
364a0 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
364b0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
364c0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
364d0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
364e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
364f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36500 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
36510 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
36520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
36530 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
36540 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
36550 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
36560 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
36570 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
36580 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36590 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
365a0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
365b0 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
365c0 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
365d0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
365e0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
365f0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
36600 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
36610 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
36620 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
36630 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
36640 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
36650 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36660 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
36670 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
36680 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
36690 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
366a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
366b0 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
366c0 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
366d0 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
366e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
366f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36700 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
36710 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
36720 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
36730 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
36740 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
36750 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36760 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
36770 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
36780 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
36790 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
367a0 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
367b0 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
367c0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
367d0 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
367e0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
367f0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
36800 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
36810 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
36820 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
36830 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
36840 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
36850 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
36860 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
36870 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36880 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36890 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
368a0 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
368b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
368c0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
368d0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
368e0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
368f0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36900 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36910 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36920 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36930 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36940 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
36950 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36960 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
36970 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
36980 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
36990 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
369a0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
369b0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
369c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
369d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
369e0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
369f0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
36a00 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36a10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
36a20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
36a30 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
36a40 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36a50 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
36a60 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36a70 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36a80 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36a90 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
36aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
36ab0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
36ac0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
36ad0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
36ae0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
36af0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36b00 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
36b10 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
36b20 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
36b30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
36b40 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36b50 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
36b60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36b70 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
36b80 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
36b90 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36ba0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
36bb0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
36bc0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
36bd0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
36be0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
36bf0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36c00 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
36c10 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
36c20 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
36c30 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
36c40 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
36c50 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
36c60 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
36c70 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36c80 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
36c90 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
36ca0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
36cb0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
36cc0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36cd0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
36ce0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
36cf0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
36d00 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
36d10 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
36d20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
36d30 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
36d40 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
36d50 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
36d60 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
36d70 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
36d80 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
36d90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36da0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
36db0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36dc0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
36dd0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
36de0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36df0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
36e00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
36e10 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
36e20 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36e30 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
36e40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36e50 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
36e60 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
36e70 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
36e80 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
36e90 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
36ea0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
36eb0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
36ec0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
36ed0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
36ee0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
36ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
36f00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
36f10 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
36f20 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
36f30 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
36f40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36f50 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
36f60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36f70 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36f80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36f90 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
36fa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36fb0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
36fc0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36fd0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
36fe0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
36ff0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
37000 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
37010 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
37020 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
37030 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
37040 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
37050 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
37060 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
37070 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
37080 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
37090 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
370a0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
370b0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
370c0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
370d0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
370e0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
370f0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
37100 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
37110 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
37120 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
37130 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
37140 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
37150 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
37160 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
37170 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37190 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
371a0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
371b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
371c0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
371d0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
371e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
371f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
37200 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37210 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37220 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
37230 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
37240 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
37250 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
37260 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
37270 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37280 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37290 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
372a0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
372b0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
372c0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
372d0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
372e0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
372f0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
37300 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
37310 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
37320 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
37330 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
37340 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
37350 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
37360 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
37370 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
37380 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
37390 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
373a0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
373b0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
373c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
373d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
373e0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
373f0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
37400 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37410 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37420 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37430 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
37440 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
37450 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37460 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37470 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37480 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
37490 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
374a0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
374b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
374c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
374d0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
374e0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
374f0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
37500 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
37510 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
37520 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
37530 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
37540 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
37550 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
37560 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
37570 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
37580 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
37590 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
375a0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
375b0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
375c0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
375d0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
375e0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
375f0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
37600 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
37610 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
37620 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
37630 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
37640 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
37650 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
37660 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
37670 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
37680 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37690 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
376a0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
376b0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
376c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
376d0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
376e0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
376f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37700 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
37710 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
37720 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
37730 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
37740 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
37750 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
37760 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
37770 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
37780 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
37790 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
377a0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
377b0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
377c0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
377d0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
377e0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
377f0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
37800 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
37810 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
37820 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
37830 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
37840 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
37850 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
37860 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
37870 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
37880 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
37890 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
378a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
378b0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
378c0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
378d0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
378e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
378f0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
37900 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
37910 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37920 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
37930 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
37940 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
37950 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
37960 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37970 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
37980 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
37990 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
379a0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
379b0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
379c0 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
379d0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
379e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
379f0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37a00 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
37a10 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
37a20 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
37a30 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
37a40 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37a50 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
37a60 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
37a70 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
37a80 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
37a90 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
37aa0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
37ab0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
37ac0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
37ad0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
37ae0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
37af0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
37b00 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
37b10 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
37b20 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
37b30 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37b40 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
37b50 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
37b60 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
37b70 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
37b80 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
37b90 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37ba0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37bb0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
37bc0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
37bd0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
37be0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37bf0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37c00 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37c10 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
37c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
37c30 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37c40 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
37c50 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
37c60 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
37c70 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
37c80 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
37c90 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
37ca0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
37cb0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
37cc0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
37cd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
37ce0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37cf0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37d00 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37d10 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
37d20 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
37d30 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
37d40 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37d50 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37d60 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37d70 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37d80 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37d90 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37da0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37db0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
37dc0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
37dd0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37de0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37df0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37e00 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37e10 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
37e20 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
37e30 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37e40 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37e50 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37e60 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
37e70 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37e80 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
37e90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
37ea0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
37eb0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
37ec0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
37ed0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
37ee0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37ef0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37f00 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37f10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37f20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37f30 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37f40 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37f50 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37f60 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37f70 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
37f80 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
37f90 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
37fa0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
37fb0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
37fc0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
37fd0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
37fe0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
37ff0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
38000 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
38010 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
38020 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
38030 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
38040 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
38050 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
38060 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
38070 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
38080 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
38090 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
380a0 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
380b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
380c0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
380d0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
380e0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
380f0 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
38100 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
38110 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
38120 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
38130 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
38140 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
38150 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
38160 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
38170 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
38180 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
38190 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
381a0 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
381b0 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
381c0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
381d0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
381e0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
381f0 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
38200 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
38210 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
38220 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
38230 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
38240 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
38250 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
38260 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
38270 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
38280 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
38290 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
382a0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
382b0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
382c0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
382d0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
382e0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
382f0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
38300 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
38310 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
38320 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
38330 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
38340 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
38350 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
38360 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
38370 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
38380 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
38390 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
383a0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
383b0 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
383c0 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
383d0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
383e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
383f0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
38400 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
38410 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
38420 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
38430 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
38440 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
38450 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
38460 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
38470 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
38480 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
38490 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
384a0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
384b0 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
384c0 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
384d0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
384e0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
384f0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
38500 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
38510 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
38520 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38530 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
38540 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
38550 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
38560 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
38570 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
38580 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38590 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
385a0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
385b0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
385c0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
385d0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
385e0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
385f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38600 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
38610 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
38620 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
38630 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
38640 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
38650 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
38660 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
38670 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
38680 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
38690 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
386a0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
386b0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
386c0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
386d0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
386e0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
386f0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
38700 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
38710 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
38720 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38730 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
38740 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
38750 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
38760 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
38770 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
38780 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
38790 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
387a0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
387b0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
387c0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
387d0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
387e0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
387f0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable poi