/ Hex Artifact Content
Login

Artifact 36d91c7ca79b9fb35831a0f097f4fcb653819a10:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5740: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5750: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5760: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5770: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5780: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5790: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
57a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
57b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
57c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
57d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
57f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5800: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5810: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5820: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5830: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5850: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5860: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5870: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
58b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
58d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5900: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5910: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5920: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5940: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5950: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5960: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5980: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
59b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
59d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
59f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5a10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5a30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5aa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ac0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ae0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5af0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5b00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5b30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5bb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5bf0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5c30: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5c40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c60: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5c70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5c80: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5c90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cb0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5cd0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5ce0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d00: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5d10: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5d20: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d50: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5d60: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5d70: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5da0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5dc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5dd0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5df0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5e00: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5e10: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5e20: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5e30: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5e40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5e50: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5e60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e70: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5e80: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5e90: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5ea0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5eb0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5ec0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5ed0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5ee0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5ef0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5f00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5f20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5f30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5f60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5f70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5f80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5f90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5fa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5fb0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5fc0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5fd0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5fe0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5ff0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6000: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6010: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6020: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6030: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6040: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6050: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6060: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6070: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6080: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6090: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
60a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
60b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
60c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
60d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
60e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
60f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6100: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6110: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6120: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6130: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6140: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6150: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6160: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6170: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6180: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6190: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
61a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
61b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
61c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
61d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
61e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
61f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6200: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6220: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6230: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6240: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6250: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6260: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6270: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6280: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6290: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
62a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
62b0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
62c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
62e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
62f0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6300: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6320: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6350: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6370: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
63a0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
63b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
63c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
63d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63e0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
63f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6400: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6410: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6430: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6440: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6450: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6460: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6470: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6480: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
64a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
64b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
64c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
64e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
64f0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6510: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6520: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6540: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6550: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6560: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6570: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6580: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6590: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
65a0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
65b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
65c0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
65d0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
65e0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
65f0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6600: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6610: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6620: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6640: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6650: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6660: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6670: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6680: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6690: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
66b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
66c0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
66e0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
66f0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6700: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6710: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6720: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6730: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6740: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6760: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6770: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6780: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6790: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
67a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
67b0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
67c0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
67d0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
67e0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
67f0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6800: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6810: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6830: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6840: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6850: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6860: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6870: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6880: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6890: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
68a0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
68b0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
68c0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
68d0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
68e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
68f0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6900: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6920: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6930: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6940: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6950: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6960: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6970: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6980: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6990: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69a0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
69b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69c0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
69d0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
69e0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
69f0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6a00: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6a10: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6a20: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6a30: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6a40: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6a50: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6a60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6a80: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6a90: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6aa0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6ab0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6ac0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6ad0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6ae0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6af0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6b00: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6b10: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6b20: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6b30: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6b40: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6b50: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6b60: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6b70: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6b80: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6b90: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6ba0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6bb0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6bc0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6bd0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6be0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6bf0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6c10: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6c20: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6c30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c40: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6c50: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6c60: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6c70: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6c80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6c90: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6ca0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6cb0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6cc0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6cd0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6ce0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6cf0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6d00: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6d10: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6d20: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6d30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6d40: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6d50: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6d60: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6d70: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6d80: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6d90: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6da0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6db0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6dc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6de0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6df0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6e00: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6e10: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6e20: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6e30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e40: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6e50: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6e60: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6e70: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e80: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6e90: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6ea0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6eb0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6ed0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6ee0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6ef0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6f00: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6f10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6f20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6f30: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6f40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6f50: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6f60: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6f70: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6f80: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6f90: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6fa0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6fb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6fc0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6fd0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6fe0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6ff0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7000: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7010: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7020: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7030: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7040: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7050: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7060: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7070: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7080: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7090: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
70a0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
70b0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
70c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
70d0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
70e0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
70f0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7100: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7110: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7120: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7130: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7140: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7150: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7160: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7170: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7180: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7190: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
71a0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
71b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
71c0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
71d0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
71e0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
71f0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7200: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7230: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7240: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7250: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7260: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7270: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7280: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7290: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
72a0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
72b0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
72c0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
72d0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
72e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
72f0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7300: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7310: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7320: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7330: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7340: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7350: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7360: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7370: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7380: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7390: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
73b0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
73d0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
73e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73f0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7400: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7410: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7420: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7430: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7440: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7450: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7460: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7470: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7480: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7490: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
74a0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
74b0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
74c0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
74d0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
74e0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
74f0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7500: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7510: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7520: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7530: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7540: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7550: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7560: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7570: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7580: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7590: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
75a0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
75b0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
75c0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
75d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
75e0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
75f0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7600: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7610: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7620: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7630: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7640: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7650: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7660: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7670: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7680: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7690: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
76a0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
76b0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
76c0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
76d0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
76e0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
76f0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7700: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7710: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7720: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7730: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7740: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7750: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7760: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7770: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7780: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7790: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
77a0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
77b0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
77c0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
77d0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
77e0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
77f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7800: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7810: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7820: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7830: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7840: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7850: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7860: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7870: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7880: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7890: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
78a0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
78b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
78c0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
78d0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
78e0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
78f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7900: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7910: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
7920: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
7930: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7940: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7950: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7960: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7970: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7980: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7990: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
79a0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
79b0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
79c0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
79d0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
79e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7a00: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7a10: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7a20: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7a30: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7a40: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7a50: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7a60: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a80: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7aa0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ac0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ae0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7b10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b20: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b40: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b60: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7ba0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7bb0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7bc0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7bd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7be0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bf0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7c00: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7c10: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7c20: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7c30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7c40: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7c50: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7c60: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7c70: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7c80: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7c90: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7ca0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7cb0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7cc0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7cd0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7cf0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7d00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7d10: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7d20: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7d30: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7d40: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7d50: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7d60: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7d70: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7d80: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7d90: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7da0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7db0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7dc0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7dd0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7de0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7df0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7e00: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7e10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7e20: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7e30: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7e40: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7e50: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7e60: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7e70: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7e80: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7e90: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7ea0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7eb0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7ec0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7ed0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7ee0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7ef0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7f00: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7f10: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7f20: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7f30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7f40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7f50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f60: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7f70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7f80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7f90: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7fa0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7fb0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7fc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7fd0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7fe0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7ff0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8000: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8010: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8020: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8030: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8040: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8050: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8060: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8070: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8080: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8090: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
80a0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
80b0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
80c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
80d0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
80e0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
80f0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8100: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8110: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8120: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8130: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8140: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8150: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8160: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8170: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8180: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8190: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
81a0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
81b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
81c0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
81d0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
81e0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
81f0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8200: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8210: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8220: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8230: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8240: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8250: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8260: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8270: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8280: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8290: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
82a0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
82b0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
82c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
82d0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
82e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
82f0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8300: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8310: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8320: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
8330: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8340: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8350: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8360: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8370: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8380: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8390: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
83a0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
83b0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
83c0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
83d0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
83e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
83f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8400: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8420: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8430: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8440: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8450: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8460: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8470: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8480: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8490: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
84a0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
84b0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
84c0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
84d0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
84e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
84f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8500: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8510: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8520: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8530: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8540: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8550: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8560: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8570: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8580: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8590: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
85a0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
85b0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
85c0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
85d0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
85e0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
85f0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8600: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8610: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8630: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8640: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8650: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8660: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8670: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8680: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8690: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
86a0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
86b0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
86c0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
86d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
86e0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
86f0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8700: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8710: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8720: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8730: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8740: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8750: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8760: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8770: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8780: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8790: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
87a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
87b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
87c0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
87d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
87e0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
87f0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8800: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8810: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8820: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8830: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8840: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8850: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8860: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8870: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8890: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
88a0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
88b0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
88c0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
88d0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
88e0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
88f0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8900: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8910: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8920: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8930: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8940: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8950: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8960: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8970: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8980: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8990: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
89a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
89b0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
89c0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
89d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
89e0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
89f0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8a00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8a10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a20: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8a30: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8a40: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8a50: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8a60: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8a80: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8a90: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8aa0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8ab0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8ac0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8ad0: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8ae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8af0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8b00: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8b10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8b20: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8b30: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8b40: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8b50: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8b60: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8b70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8b80: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8b90: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8ba0: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8bb0: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8bc0: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8bd0: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8be0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8bf0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8c00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8c10: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8c20: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8c30: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8c40: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8c50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8c60: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8c70: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8c80: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8c90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8ca0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8cb0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8cc0: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8cd0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8ce0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8cf0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8d00: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8d10: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8d20: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8d30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d40: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8d50: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8d60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8d70: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8d80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8d90: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8da0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8db0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8dc0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8dd0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8de0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8df0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8e00: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8e10: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8e20: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8e30: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8e40: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e50: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8e60: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8e70: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8e80: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8e90: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8ea0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8eb0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8ec0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8ed0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8ee0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8ef0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8f00: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8f10: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8f20: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8f30: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8f40: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8f50: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8f60: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8f70: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
8f80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
8f90: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
8fa0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
8fb0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
8fc0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
8fd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8fe0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8ff0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9000: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9010: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9020: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9030: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9040: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9050: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9060: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9070: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9080: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9090: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
90a0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
90b0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
90c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
90d0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
90e0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
90f0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9100: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9110: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9120: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9130: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9140: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9150: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9160: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9170: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9180: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9190: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
91a0: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
91b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
91c0: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
91d0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
91e0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
91f0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9200: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9210: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9220: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9230: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9240: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9250: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9260: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9270: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9280: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9290: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
92a0: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
92b0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
92c0: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
92d0: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
92e0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
92f0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9300: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9310: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9320: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9330: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9340: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9350: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9360: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9370: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9380: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9390: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
93a0: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
93b0: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
93c0: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
93d0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
93e0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
93f0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9400: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9410: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
9420: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
9430: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9440: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9450: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9460: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9480: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9490: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
94a0: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
94b0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
94c0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
94d0: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
94e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
94f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9500: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9510: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9520: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
9530: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9550: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9560: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9570: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9580: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9590: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
95a0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
95b0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
95c0: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
95d0: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
95e0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
95f0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
9600: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
9610: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
9620: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
9630: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9640: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9650: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9660: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9670: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9680: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9690: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
96a0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
96b0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
96c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
96d0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
96e0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
96f0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9700: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
9710: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
9720: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9730: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9740: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9750: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9760: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9770: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9780: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9790: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
97a0: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
97b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
97c0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
97d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
97e0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
97f0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
9800: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
9810: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
9820: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
9830: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9840: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9850: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9860: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9870: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9880: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9890: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
98a0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
98b0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
98c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
98d0: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
98e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
98f0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
9900: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
9910: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
9920: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
9930: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9940: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9950: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9960: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9970: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9980: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
99a0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
99b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
99c0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
99d0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
99e0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
99f0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9a00: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9a10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9a20: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9a30: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9a40: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9a50: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9a60: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9a70: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9a80: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9a90: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9aa0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9ab0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9ac0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9ad0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9ae0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9af0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9b00: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9b10: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9b20: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9b30: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9b40: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9b50: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9b60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9b70: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9b80: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9ba0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9bb0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9bc0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9bd0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9be0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9bf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9c00: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9c10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9c20: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9c30: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9c40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9c50: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9c60: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9c70: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9c80: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9c90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9ca0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9cb0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9cc0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9cd0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9ce0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9cf0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9d00: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9d10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9d20: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9d30: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9d50: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9d60: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9d70: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9d80: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9d90: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9da0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9db0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9dc0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9dd0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9de0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9df0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9e00: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9e10: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9e20: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9e30: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9e40: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9e50: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9e60: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9e70: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9e80: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9e90: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9ea0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9eb0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9ec0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9ed0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9ee0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9ef0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9f00: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9f10: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9f20: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9f30: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9f40: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9f50: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9f60: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9f70: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
9f80: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
9f90: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
9fa0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
9fb0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
9fc0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
9fd0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
9fe0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9ff0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a000: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a010: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a020: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a030: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a040: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a050: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a060: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a070: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a080: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a090: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a0a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a0b0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a0c0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a0d0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a0e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a0f0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a100: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a110: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a120: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a130: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a140: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a150: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a160: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a170: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f  tatements..** </
a180: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ul>.**.** <li>[[
a190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a1a0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
a1b0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a1c0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a1d0: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a1e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a1f0: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a200: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a210: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a220: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a230: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a240: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a250: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a260: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a270: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a280: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a290: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a2a0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a2b0: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a2c0: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a2d0: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a2e0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a2f0: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a300: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a310: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a320: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a330: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a340: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a350: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a360: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a370: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a380: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a390: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a3a0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a3b0: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a3c0: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a3d0: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a3e0: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a3f0: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a400: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a410: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a420: 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
a440: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
a450: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
a460: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
a470: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a480: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
a490: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
a4a0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a4b0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
a4c0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
a4d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a4e0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
a4f0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
a500: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
a510: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
a520: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
a530: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
a540: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
a550: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
a560: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
a570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a580: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
a590: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
a5a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a5b0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a5c0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
a5d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a5e0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
a5f0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
a600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a610: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
a620: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
a630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a640: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
a650: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
a660: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a670: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a680: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
a690: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a6a0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
a6b0: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
a6c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
a6d0: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
a6e0: 20 20 20 20 20 20 31 35 0a 0a 2f 2a 0a 2a 2a 20        15../*.** 
a6f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
a700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
a710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
a720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
a730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
a740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
a750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
a760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
a770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
a780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
a790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
a7a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
a7b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
a7c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
a7d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
a7e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
a7f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
a800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
a810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
a820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
a830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
a840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
a860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
a870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
a890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
a8a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
a8b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a8c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a8d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
a8e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
a8f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
a900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
a910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
a920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
a930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
a940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
a950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
a960: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
a970: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
a980: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
a990: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
a9a0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
a9b0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
a9c0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
a9d0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
a9e0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
a9f0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
aa00: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
aa10: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
aa20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
aa30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
aa40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
aa50: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
aa60: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
aa70: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
aa80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
aa90: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
aaa0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
aab0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
aac0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
aad0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
aae0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
aaf0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
ab00: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
ab10: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
ab20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
ab30: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
ab40: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
ab50: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
ab60: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
ab70: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
ab80: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
ab90: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
aba0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
abb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
abc0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
abd0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
abe0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
abf0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
ac00: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
ac10: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
ac20: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
ac30: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
ac40: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
ac50: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ac60: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
ac70: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ac80: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
ac90: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
aca0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
acb0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
acc0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
acd0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
ace0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
acf0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
ad00: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
ad10: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ad20: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
ad30: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
ad40: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
ad50: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
ad60: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
ad70: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
ad80: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
ad90: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
ada0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
adb0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
adc0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
add0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
ade0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
adf0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
ae00: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
ae10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ae20: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
ae30: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
ae40: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
ae50: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
ae60: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
ae70: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
ae80: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
ae90: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
aea0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
aeb0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
aec0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
aed0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
aee0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
aef0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
af00: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
af10: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
af20: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
af30: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
af40: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
af50: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
af60: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
af70: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
af80: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
af90: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
afa0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
afb0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
afc0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
afd0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
afe0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
aff0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
b000: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
b010: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
b020: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
b030: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
b040: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
b050: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
b060: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
b070: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
b080: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
b090: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
b0a0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
b0b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
b0c0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
b0d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
b0e0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
b0f0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
b100: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
b110: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
b120: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
b130: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b140: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
b150: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
b160: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
b170: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
b180: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
b190: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
b1a0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
b1b0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
b1c0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
b1d0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
b1e0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
b1f0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
b200: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
b210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b220: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
b230: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b240: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
b250: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
b260: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
b270: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
b280: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
b290: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
b2a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
b2b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
b2c0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
b2d0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
b2e0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
b2f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
b300: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
b310: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
b320: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
b330: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
b340: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
b350: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
b360: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
b370: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
b380: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
b390: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
b3a0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
b3b0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
b3c0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
b3d0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
b3e0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
b3f0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
b400: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
b410: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
b420: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b430: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b440: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
b450: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b460: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
b470: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b480: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
b490: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b4a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
b4b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
b4c0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
b4d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b4e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
b4f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b500: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
b510: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
b520: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b530: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
b540: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
b550: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
b560: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
b570: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
b580: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
b590: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
b5a0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
b5b0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
b5c0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
b5d0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
b5e0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
b5f0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
b600: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
b610: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
b620: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
b630: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
b640: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
b650: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
b660: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
b670: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
b680: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
b690: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
b6a0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
b6b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
b6c0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
b6d0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
b6e0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
b6f0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
b700: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
b710: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
b720: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
b730: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
b740: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
b750: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
b760: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
b770: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
b780: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
b790: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
b7a0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
b7b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
b7c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b7d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
b7e0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b7f0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
b800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
b810: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b820: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
b830: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
b840: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
b850: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
b860: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b870: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
b880: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
b890: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
b8a0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
b8b0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
b8c0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
b8d0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
b8e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b8f0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
b900: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
b910: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
b920: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
b930: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
b940: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
b950: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
b960: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
b970: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
b980: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
b990: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
b9a0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
b9b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
b9c0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
b9d0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
b9e0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
b9f0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
ba00: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
ba10: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
ba20: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
ba30: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
ba40: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
ba50: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
ba60: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
ba70: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
ba80: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
ba90: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
baa0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
bab0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
bac0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
bad0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
bae0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
baf0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
bb00: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
bb10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
bb20: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
bb30: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
bb40: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
bb50: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
bb60: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
bb70: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
bb80: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
bb90: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
bba0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
bbb0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
bbc0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
bbd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
bbe0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
bbf0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
bc00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bc10: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
bc20: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
bc30: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
bc40: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
bc50: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
bc60: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
bc70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
bc80: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
bc90: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
bca0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
bcb0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
bcc0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
bcd0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
bce0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
bcf0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
bd00: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
bd10: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
bd20: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
bd30: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
bd40: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
bd50: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
bd60: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
bd70: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
bd80: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
bd90: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
bda0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
bdb0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
bdc0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
bdd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
bde0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
bdf0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
be00: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
be10: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
be20: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
be30: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
be40: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
be50: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
be60: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
be70: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
be80: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
be90: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
bea0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
beb0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
bec0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
bed0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
bee0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
bef0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
bf00: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
bf10: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
bf20: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
bf30: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
bf40: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
bf50: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
bf60: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
bf70: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
bf80: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
bf90: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
bfa0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
bfb0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
bfc0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
bfd0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
bfe0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
bff0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
c000: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
c010: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
c020: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
c030: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
c040: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
c050: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
c060: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
c070: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
c080: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
c090: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
c0a0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
c0b0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
c0c0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
c0d0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
c0e0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
c0f0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
c100: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
c110: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
c120: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
c130: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
c140: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
c150: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
c160: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
c170: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
c180: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
c190: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
c1a0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
c1b0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
c1c0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
c1d0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
c1e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
c1f0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
c200: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
c210: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
c220: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
c230: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
c240: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c250: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c260: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
c270: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
c280: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
c290: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
c2a0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
c2b0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
c2c0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
c2d0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
c2e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
c2f0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
c300: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c310: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
c320: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
c330: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
c340: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
c350: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
c360: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
c370: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
c380: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
c390: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
c3a0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
c3b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
c3c0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
c3d0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
c3e0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
c3f0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
c400: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
c410: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
c420: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
c430: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
c440: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
c450: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
c460: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
c470: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
c480: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
c490: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
c4a0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
c4b0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
c4c0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
c4d0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
c4e0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
c4f0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
c500: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
c510: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
c520: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
c530: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
c540: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
c550: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
c560: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
c570: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
c580: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
c590: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
c5a0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
c5b0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
c5c0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
c5d0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
c5e0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
c5f0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
c600: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
c610: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
c620: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
c630: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
c640: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
c650: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
c660: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
c670: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
c680: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
c690: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
c6a0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
c6b0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
c6c0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
c6d0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
c6e0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
c6f0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
c700: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
c710: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
c720: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c730: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
c740: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
c750: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
c760: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
c770: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
c780: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
c790: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
c7a0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
c7b0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
c7c0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
c7d0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
c7e0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
c7f0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
c800: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
c810: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
c820: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
c830: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
c840: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
c850: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
c860: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
c870: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
c880: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
c890: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
c8a0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
c8b0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
c8c0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
c8d0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
c8e0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
c8f0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
c900: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
c910: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c920: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c930: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
c940: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
c950: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c960: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
c970: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
c980: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c990: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c9a0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
c9b0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
c9c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c9d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c9e0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
c9f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
ca00: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
ca10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ca20: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ca30: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
ca40: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
ca50: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
ca60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ca70: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
ca80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
ca90: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
caa0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
cab0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
cac0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
cad0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
cae0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
caf0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
cb00: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
cb10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
cb20: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
cb30: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
cb40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
cb50: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
cb60: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
cb70: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
cb80: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
cb90: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
cba0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
cbb0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
cbc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
cbd0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
cbe0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
cbf0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
cc00: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
cc10: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
cc20: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
cc30: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
cc40: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
cc50: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
cc60: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
cc70: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
cc80: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
cc90: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
cca0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
ccb0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
ccc0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ccd0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
cce0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
ccf0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
cd00: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
cd10: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
cd20: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
cd30: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
cd40: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
cd50: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cd60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cd70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
cd80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
cd90: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
cda0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
cdb0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
cdc0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
cdd0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
cde0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
cdf0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ce00: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ce10: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ce20: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ce30: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ce40: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ce50: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ce60: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ce70: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ce80: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ce90: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
cea0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ceb0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
cec0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ced0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
cee0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
cef0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
cf00: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
cf10: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
cf20: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
cf30: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
cf40: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
cf50: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cf60: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
cf70: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
cf80: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
cf90: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
cfa0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
cfb0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
cfc0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
cfd0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
cfe0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
cff0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
d000: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
d010: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
d020: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d030: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
d040: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d050: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
d060: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d070: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d080: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
d090: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
d0a0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d0b0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
d0c0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
d0d0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
d0e0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
d0f0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
d100: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
d110: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
d120: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
d130: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
d140: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
d150: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
d160: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
d170: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
d180: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
d190: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
d1a0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
d1b0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
d1c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
d1d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d1e0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d1f0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
d200: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
d210: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d220: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
d230: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
d240: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
d250: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
d260: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
d270: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
d280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d290: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
d2a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
d2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d2c0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
d2d0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
d2e0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
d2f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d300: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
d310: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
d320: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d330: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d340: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
d350: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
d360: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d370: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
d380: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
d390: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
d3a0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
d3b0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
d3c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d3d0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
d3e0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
d3f0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
d400: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
d410: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
d420: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d430: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
d440: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
d450: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
d460: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d470: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
d480: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
d490: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d4a0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
d4b0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
d4c0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
d4d0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
d4e0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
d4f0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
d500: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
d510: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
d520: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
d530: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
d540: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
d550: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
d560: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
d570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
d580: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
d590: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
d5a0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
d5b0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
d5c0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d5d0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
d5e0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
d5f0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
d600: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
d610: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
d620: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d630: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
d640: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
d650: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
d660: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
d670: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
d680: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
d690: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
d6a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
d6b0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
d6c0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
d6d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d6e0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
d6f0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
d700: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
d710: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
d720: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
d730: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
d740: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
d750: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
d760: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
d770: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
d780: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
d790: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
d7a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d7b0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
d7c0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
d7d0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
d7e0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d7f0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
d800: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d810: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
d820: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
d830: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
d840: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
d850: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
d860: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
d870: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
d880: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
d890: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
d8a0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
d8b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
d8c0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
d8d0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
d8e0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
d8f0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
d900: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
d910: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
d920: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
d930: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
d940: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
d950: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
d960: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
d970: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
d980: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
d990: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
d9a0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
d9b0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
d9c0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d9d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d9e0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
d9f0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
da00: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
da10: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
da20: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
da30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
da40: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
da50: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
da60: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
da70: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
da80: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
da90: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
daa0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
dab0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
dac0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
dad0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
dae0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
daf0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
db00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
db10: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
db20: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
db30: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
db40: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
db50: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
db60: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
db70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
db80: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
db90: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
dba0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dbb0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
dbc0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
dbd0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
dbe0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
dbf0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
dc00: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
dc10: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
dc20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dc30: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
dc40: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
dc50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dc60: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
dc70: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
dc80: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
dc90: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
dca0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
dcb0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
dcc0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
dcd0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
dce0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
dcf0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
dd00: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
dd10: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
dd20: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
dd30: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
dd40: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
dd50: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
dd60: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
dd70: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
dd80: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
dd90: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
dda0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
ddb0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
ddc0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
ddd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
dde0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
ddf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
de00: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
de10: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
de20: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
de30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
de40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
de50: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
de60: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
de70: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
de80: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
de90: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
dea0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
deb0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
dec0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
ded0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
dee0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
def0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
df00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
df10: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
df20: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
df30: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
df40: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
df50: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
df60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
df70: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
df80: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
df90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
dfa0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
dfb0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
dfc0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
dfd0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
dfe0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
dff0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
e000: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
e010: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
e020: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
e030: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
e040: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
e050: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
e060: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
e070: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
e080: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e090: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
e0a0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
e0b0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
e0c0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
e0d0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
e0e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
e0f0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
e100: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
e110: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
e120: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
e130: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e140: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
e150: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e160: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e170: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
e180: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
e190: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
e1a0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
e1b0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
e1c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e1d0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
e1e0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
e1f0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e200: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
e210: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
e220: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
e230: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
e240: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
e250: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
e260: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
e270: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e280: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
e290: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
e2a0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
e2b0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
e2c0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
e2d0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e2e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
e2f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
e300: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
e310: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
e320: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
e330: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
e340: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
e350: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
e360: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
e370: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
e380: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
e390: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
e3a0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
e3b0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
e3c0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
e3d0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
e3e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
e3f0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
e400: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
e410: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
e420: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
e430: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
e440: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
e450: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
e460: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
e470: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
e480: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
e490: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
e4a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e4b0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
e4c0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
e4d0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
e4e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
e4f0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
e500: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
e510: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
e520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e530: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
e540: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
e550: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
e560: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
e570: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
e580: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
e590: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e5a0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
e5b0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
e5c0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
e5d0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
e5e0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
e5f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
e600: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e610: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e620: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
e630: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
e640: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
e650: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
e660: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
e670: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
e680: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
e690: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
e6a0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
e6b0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
e6c0: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
e6d0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
e6e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
e6f0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
e700: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
e710: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
e720: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
e730: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e740: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
e750: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
e760: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
e770: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e780: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
e790: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
e7a0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
e7b0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
e7c0: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
e7d0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
e7e0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
e7f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e800: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
e810: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
e820: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
e830: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
e840: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
e850: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
e860: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
e870: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
e880: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e890: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
e8a0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
e8b0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
e8c0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
e8d0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e8e0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
e8f0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
e900: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
e910: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
e920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
e930: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
e940: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
e950: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
e960: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
e970: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
e980: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
e990: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
e9a0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
e9b0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
e9c0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
e9d0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
e9e0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
e9f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ea00: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
ea10: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
ea20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ea30: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
ea40: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
ea50: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ea60: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
ea70: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
ea80: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
ea90: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
eaa0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
eab0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
eac0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
ead0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
eae0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
eaf0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
eb00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eb10: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
eb20: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
eb30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
eb40: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
eb50: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
eb60: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
eb70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
eb80: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
eb90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eba0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
ebb0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
ebc0: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
ebd0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
ebe0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
ebf0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
ec00: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
ec10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ec20: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
ec30: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
ec40: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
ec50: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
ec60: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ec70: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
ec80: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
ec90: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
eca0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
ecb0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
ecc0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
ecd0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
ece0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
ecf0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
ed00: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ed10: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
ed20: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
ed30: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
ed40: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
ed50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ed60: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ed70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
ed80: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ed90: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
eda0: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
edb0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
edc0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
edd0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
ede0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
edf0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
ee00: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
ee10: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
ee20: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
ee30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ee40: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
ee50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
ee60: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
ee70: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ee80: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ee90: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
eea0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
eeb0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
eec0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
eed0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
eee0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
eef0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
ef00: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
ef10: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
ef20: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
ef30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
ef40: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
ef50: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
ef60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
ef70: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
ef80: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ef90: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
efa0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
efb0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
efc0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
efd0: 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
efe0: 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
eff0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
f000: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
f010: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f020: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
f030: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
f040: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
f050: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f060: 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
f070: 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
f080: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
f090: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
f0a0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
f0b0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
f0c0: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
f0d0: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
f0e0: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
f0f0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
f100: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
f110: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
f120: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
f130: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
f140: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
f150: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f160: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
f170: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
f180: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
f190: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
f1a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f1b0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
f1c0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
f1d0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
f1e0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
f1f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
f200: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
f210: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f220: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
f230: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
f240: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
f250: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
f260: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
f270: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f280: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
f290: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f2a0: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
f2b0: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
f2c0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f2d0: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
f2e0: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
f2f0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
f300: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f310: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f320: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f330: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f340: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f350: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f360: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f370: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f380: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f390: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f3a0: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f3b0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f3c0: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f3d0: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f3e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f3f0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f400: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f410: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f420: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f430: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f440: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
f450: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
f460: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
f470: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
f480: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
f490: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
f4a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f4b0: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
f4c0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
f4d0: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
f4e0: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
f4f0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f500: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f510: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f520: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
f530: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
f540: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
f550: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
f560: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
f570: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
f580: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
f590: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
f5a0: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
f5b0: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
f5c0: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
f5d0: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
f5e0: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
f5f0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
f600: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
f610: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
f620: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
f630: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
f640: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
f650: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f660: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
f670: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
f680: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
f690: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f6a0: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
f6b0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
f6c0: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
f6d0: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
f6e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f6f0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
f700: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
f710: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
f720: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
f730: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
f740: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
f750: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
f760: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
f770: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
f780: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
f790: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
f7a0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
f7b0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
f7c0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
f7d0: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
f7e0: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
f7f0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
f800: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f810: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
f820: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f830: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
f840: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
f850: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
f860: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f870: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
f880: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
f890: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
f8a0: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
f8b0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
f8c0: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
f8d0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
f8e0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f8f0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
f900: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
f910: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
f920: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
f930: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
f940: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
f950: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f960: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
f970: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
f980: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
f990: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
f9a0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
f9b0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
f9c0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
f9d0: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
f9e0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
f9f0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
fa00: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
fa10: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
fa20: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
fa30: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
fa40: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
fa50: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
fa60: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
fa70: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
fa80: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
fa90: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
faa0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
fab0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
fac0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
fad0: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
fae0: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
faf0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
fb00: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
fb10: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
fb20: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
fb30: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
fb40: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
fb50: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
fb60: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
fb70: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
fb80: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
fb90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fba0: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
fbb0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
fbc0: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
fbd0: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
fbe0: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
fbf0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
fc00: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
fc10: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
fc20: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
fc30: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fc40: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
fc50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
fc60: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
fc70: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
fc80: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
fc90: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
fca0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
fcb0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
fcc0: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
fcd0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
fce0: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
fcf0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
fd00: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
fd10: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
fd20: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
fd30: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
fd40: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
fd50: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
fd60: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
fd70: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
fd80: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
fd90: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
fda0: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
fdb0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
fdc0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fdd0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fde0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
fdf0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
fe00: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fe10: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
fe20: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
fe30: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
fe40: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
fe50: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
fe60: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
fe70: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
fe80: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fe90: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
fea0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
feb0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
fec0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
fed0: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
fee0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
fef0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
ff00: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
ff10: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
ff20: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
ff30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
ff40: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
ff50: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
ff60: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
ff70: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
ff80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
ff90: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
ffa0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
ffb0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
ffc0: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
ffd0: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
ffe0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
fff0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
10000 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
10010 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
10020 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
10030 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
10040 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
10050 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10060 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
10070 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
10080 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10090 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
100a0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
100b0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
100c0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
100d0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
100e0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
100f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10100 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
10110 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
10120 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
10130 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10140 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10150 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10160 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10170 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
10180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10190 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
101a0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
101b0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
101c0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
101d0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
101e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
101f0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10200 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10210 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
10220 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10230 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10240 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10250 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10260 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10270 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10280 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10290 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
102a0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
102b0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
102c0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
102d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
102e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
102f0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
10300 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10310 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
10320 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
10330 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10340 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10350 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10360 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10370 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10380 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10390 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
103a0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
103b0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
103c0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
103d0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
103e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
103f0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10400 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10410 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10420 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10430 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10440 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10450 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10460 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10470 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10480 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10490 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
104a0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
104b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
104c0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
104d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
104e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
104f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
10500 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
10510 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10520 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
10530 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10540 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10550 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10560 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10570 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10580 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10590 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
105a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
105b0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
105c0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
105d0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
105e0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
105f0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
10600 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
10620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
10630 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
10640 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10650 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10660 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10670 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10690 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
106a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
106b0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
106c0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
106d0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
106e0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
106f0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
10700 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
10710 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
10720 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
10730 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
10740 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10760 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10770 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10780 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10790 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
107a0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
107b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
107c0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
107d0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
107e0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
107f0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
10800 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
10810 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
10820 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10830 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
10840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10850 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10860 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10870 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10880 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10890 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
108a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
108b0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
108c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
108d0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
108e0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
108f0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
10900 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
10910 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
10920 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
10930 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
10940 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10950 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10960 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10970 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10980 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10990 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
109a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
109b0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
109c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
109d0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
109e0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
109f0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
10a00 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
10a10 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
10a20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10a30 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
10a40 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
10a50 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
10a60 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
10a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10a80 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10a90 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
10aa0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
10ab0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
10ac0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
10ad0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10ae0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
10af0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
10b00 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
10b10 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
10b20 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
10b30 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
10b40 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10b50 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10b60 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10b70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10b80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10b90 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10ba0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10bb0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
10bc0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
10bd0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10be0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10bf0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
10c00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10c10 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
10c20 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
10c30 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
10c40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10c50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10c70 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
10c80 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
10c90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10ca0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10cb0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10cc0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10cd0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10ce0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
10cf0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10d00 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10d10 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
10d20 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
10d30 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
10d40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10d50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10d60 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
10d70 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
10d80 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10d90 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10da0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
10db0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
10dc0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
10dd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
10df0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10e00 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
10e10 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10e20 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
10e30 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
10e40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10e50 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
10e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10e70 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10e80 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10e90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10ea0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10eb0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
10ec0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
10ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
10ee0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
10ef0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
10f00 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
10f10 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10f20 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10f30 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10f40 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
10f50 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
10f60 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10f70 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10f80 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10f90 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10fa0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
10fb0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
10fc0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
10fd0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
10fe0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
10ff0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
11000 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
11010 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
11020 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11030 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
11040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11050 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
11060 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11070 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
11080 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
11090 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
110a0 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
110b0 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
110c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
110d0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
110e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110f0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
11100 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
11110 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
11120 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
11130 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
11140 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
11150 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
11160 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
11170 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
11180 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
11190 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
111a0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
111b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
111c0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
111d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
111e0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
111f0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
11200 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
11210 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
11220 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
11230 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
11240 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
11250 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
11260 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
11270 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
11280 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
11290 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
112a0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
112b0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
112c0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
112d0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
112e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
112f0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
11300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
11310 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
11320 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
11330 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
11340 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11350 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11360 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11370 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11380 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11390 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
113a0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
113b0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
113c0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
113d0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
113e0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
113f0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
11400 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
11410 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
11420 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
11430 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11440 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11450 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11460 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11470 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11480 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11490 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
114a0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
114b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
114c0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
114d0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
114e0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
114f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11500 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
11510 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
11520 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
11530 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
11540 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11550 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11560 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11570 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11580 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11590 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
115a0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
115b0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
115c0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
115d0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
115e0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
115f0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
11600 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
11610 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
11620 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
11630 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
11640 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11650 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11660 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11670 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11680 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
116a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
116b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
116c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
116d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
116e0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
116f0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
11700 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11710 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
11720 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
11730 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
11740 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11750 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11760 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11770 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11780 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11790 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
117a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
117b0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
117c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
117d0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
117e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
117f0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
11800 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11810 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11820 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
11830 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
11840 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11850 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11860 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11870 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11880 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11890 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
118a0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
118b0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
118c0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
118d0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
118e0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
118f0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
11900 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
11910 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
11920 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
11930 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
11940 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11950 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11960 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11970 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11980 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11990 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
119a0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
119b0 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
119c0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
119d0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
119e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
119f0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
11a00 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
11a10 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
11a20 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
11a30 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
11a40 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
11a50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11a60 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
11a70 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
11a80 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
11a90 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
11aa0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
11ab0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
11ac0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
11ad0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
11ae0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
11af0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
11b00 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
11b10 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
11b20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11b30 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
11b40 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
11b50 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
11b60 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11b70 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
11b80 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11b90 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
11ba0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
11bb0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
11bc0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
11bd0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
11be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11bf0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
11c00 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
11c10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11c20 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
11c30 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
11c40 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11c50 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
11c60 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
11c70 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
11c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11c90 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
11ca0 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
11cb0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
11cc0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
11cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11ce0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
11cf0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11d00 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
11d10 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
11d20 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
11d30 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11d40 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
11d50 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
11d60 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11d70 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
11d80 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
11d90 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11da0 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
11db0 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
11dc0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
11dd0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
11de0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11df0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
11e00 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
11e10 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
11e20 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
11e30 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
11e40 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11e50 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
11e60 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
11e70 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
11e80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
11e90 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
11ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
11eb0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
11ec0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
11ed0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
11ee0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11ef0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
11f00 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
11f10 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
11f20 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
11f30 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
11f40 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
11f50 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
11f60 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11f70 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
11f80 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11f90 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11fa0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
11fb0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
11fc0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
11fd0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
11fe0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
11ff0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
12000 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
12010 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
12020 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
12030 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
12040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12050 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
12060 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
12070 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12080 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12090 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
120a0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
120b0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
120c0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
120d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
120e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
120f0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
12100 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12110 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12120 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
12130 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12140 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
12150 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
12160 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12170 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12180 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12190 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
121a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
121b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
121c0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
121d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
121e0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
121f0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
12200 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12210 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12220 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12230 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12240 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12250 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12260 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12270 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12280 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12290 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
122a0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
122b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
122c0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
122d0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
122e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
122f0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
12300 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
12310 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12320 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12330 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
12340 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12360 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12370 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12380 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12390 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
123a0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
123b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
123c0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
123d0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
123e0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
123f0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12400 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12410 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12420 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
12430 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12440 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12450 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12460 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12470 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12480 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12490 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
124a0 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
124b0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
124c0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
124d0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
124e0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
124f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12500 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12510 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12530 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12540 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12550 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12560 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12570 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12580 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12590 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
125a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
125b0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
125c0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
125d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
125e0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
125f0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12600 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
12610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
12620 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
12630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12640 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12650 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12660 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12670 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12680 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12690 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
126a0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
126b0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
126c0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
126d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
126e0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
126f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
12700 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
12710 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
12720 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
12730 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
12740 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12750 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12760 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12770 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12780 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12790 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
127a0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
127b0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
127c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
127d0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
127e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
127f0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
12800 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
12810 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
12820 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
12830 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
12840 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12860 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12870 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12880 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12890 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
128a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
128b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
128c0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
128d0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
128e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
128f0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
12900 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
12910 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
12920 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
12930 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12940 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12950 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12960 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12970 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12980 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12990 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
129a0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
129b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
129c0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
129d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
129e0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
129f0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12a00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12a10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12a20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12a30 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
12a40 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12a50 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
12a60 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
12a70 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
12a80 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12a90 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
12aa0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
12ab0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12ac0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
12ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
12ae0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12b00 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
12b10 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
12b20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
12b30 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
12b40 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
12b50 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
12b60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12b70 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
12b80 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
12b90 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
12ba0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
12bb0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
12bc0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
12bd0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
12be0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
12bf0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
12c00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
12c10 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
12c20 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
12c30 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
12c40 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
12c50 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
12c60 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
12c70 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12c90 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
12ca0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
12cb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12cc0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
12cd0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
12ce0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
12cf0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
12d00 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
12d10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
12d20 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12d30 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
12d40 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12d50 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12d60 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
12d70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
12d80 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
12d90 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
12da0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
12db0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
12dc0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12dd0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
12de0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
12df0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
12e00 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
12e10 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
12e20 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
12e30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
12e40 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
12e50 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
12e60 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
12e70 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12e80 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
12e90 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
12ea0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
12eb0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
12ec0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
12ed0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
12ee0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
12ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12f00 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
12f10 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
12f20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
12f30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f40 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
12f50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12f60 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
12f70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12f80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12f90 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
12fa0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
12fb0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
12fc0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12fd0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
12fe0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
12ff0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
13000 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
13010 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
13020 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13030 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
13040 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
13050 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
13060 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
13070 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
13080 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
13090 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
130a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
130b0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
130c0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
130d0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
130e0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
130f0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
13100 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
13110 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
13120 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
13130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
13140 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
13150 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13160 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
13170 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
13180 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
13190 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
131a0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
131b0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
131c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
131d0 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
131e0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
131f0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
13200 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
13210 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
13220 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
13230 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
13240 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13250 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13260 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
13270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13280 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
13290 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
132a0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
132b0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
132c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
132d0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
132e0 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  er argument whic
132f0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
13300 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e   as.** a boolean
13310 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
13320 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
13330 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
13340 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a  ng indices for.*
13350 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  * full table sca
13360 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
13370 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20  optimizer.  The 
13380 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
13390 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
133a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
133b0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
133c0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
133d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
133e0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
133f0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
13400 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
13410 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
13420 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
13430 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
13440 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
13450 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13460 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
13470 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
13480 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
13490 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
134a0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  malfunction.** m
134b0 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20  alfunction when 
134c0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
134d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
134e0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
134f0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
13500 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
13510 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
13520 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
13530 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
13540 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
13550 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
13560 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
13570 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
13580 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13590 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
135a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
135b0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
135c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
135d0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
135e0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
135f0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
13600 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
13610 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
13620 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
13630 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
13640 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
13650 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
13660 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
13670 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
13680 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13690 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
136a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
136b0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
136c0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
136d0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
136e0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
136f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
13700 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
13710 45 5f 53 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f  E_SQLLOG pre-pro
13720 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
13730 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
13740 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
13750 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
13760 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
13770 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
13780 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
13790 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
137a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
137b0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
137c0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
137d0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
137e0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
137f0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
13800 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
13810 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
13820 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
13830 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
13840 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
13850 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
13860 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
13870 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
13880 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
13890 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
138a0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
138b0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
138c0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
138d0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
138e0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
138f0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
13900 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
13910 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
13920 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
13930 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
13940 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
13950 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
13960 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
13970 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
13980 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
13990 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
139a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
139b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
139c0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
139d0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
139e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
139f0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
13a00 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
13a10 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
13a20 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
13a30 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
13a40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13a50 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13a60 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
13a70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13a80 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13a90 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
13aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13ab0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
13ac0 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
13ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13ae0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
13af0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
13b00 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
13b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13b20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13b30 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
13b40 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13b50 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
13b60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13b70 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
13b80 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
13b90 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
13ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13bb0 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
13bc0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
13bd0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
13be0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13bf0 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
13c00 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
13c10 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
13c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13c30 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
13c40 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
13c50 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
13c60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13c70 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
13c80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13c90 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
13ca0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13cb0 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
13cc0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
13cd0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
13ce0 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
13cf0 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
13d00 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
13d10 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
13d20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13d30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
13d40 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
13d50 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
13d60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13d70 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
13d80 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
13d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13da0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
13db0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
13dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13dd0 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
13de0 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
13df0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
13e00 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
13e10 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
13e20 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
13e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13e40 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
13e50 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
13e60 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
13e70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13e80 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
13e90 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
13ea0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
13eb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13ec0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
13ed0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20  _INDEX_SCAN 20  
13ee0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
13ef0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f00 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20  SQLLOG       21 
13f10 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69   /* xSqllog, voi
13f20 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d* */../*.** CAP
13f30 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
13f40 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
13f50 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
13f60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
13f70 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
13f80 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
13f90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13fa0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
13fb0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
13fc0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
13fd0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13fe0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13ff0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
14000 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
14010 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
14020 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
14030 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
14040 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
14050 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
14060 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
14070 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
14080 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
14090 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
140a0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
140b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
140c0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
140d0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
140e0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
140f0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
14100 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
14110 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
14120 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
14130 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
14140 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
14150 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
14160 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14170 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
14180 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
14190 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
141a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
141b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
141c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
141d0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
141e0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
141f0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
14200 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14210 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
14220 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
14230 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
14240 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
14250 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14260 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
14270 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
14280 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
14290 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
142a0 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
142b0 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
142c0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
142d0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
142e0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
142f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14300 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
14310 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
14320 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
14330 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
14340 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
14350 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
14360 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
14370 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
14380 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
14390 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
143a0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
143b0 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
143c0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
143d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
143e0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
143f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
14400 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
14410 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
14420 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
14430 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
14440 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
14450 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
14460 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
14470 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
14480 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
14490 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
144a0 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
144b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
144c0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
144d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
144e0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
144f0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
14500 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
14510 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
14520 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
14530 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
14540 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
14550 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14560 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
14570 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
14580 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
14590 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
145a0 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
145b0 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
145c0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
145d0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
145e0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
145f0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
14600 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
14610 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
14620 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
14630 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
14640 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
14650 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
14660 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
14670 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
14680 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
14690 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
146a0 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
146b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
146c0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
146d0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
146e0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
146f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
14700 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
14710 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
14720 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
14730 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
14740 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
14750 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
14760 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
14770 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
14780 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
14790 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
147a0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
147b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
147c0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
147d0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
147e0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
147f0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
14800 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
14810 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
14820 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
14830 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
14840 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
14850 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14860 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
14870 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
14880 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
14890 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
148a0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
148b0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
148c0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
148d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
148e0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
148f0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
14900 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
14910 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
14920 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
14930 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
14940 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
14950 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
14960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
14970 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
14980 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
14990 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
149a0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
149b0 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
149c0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
149d0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
149e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
149f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
14a00 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
14a10 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
14a20 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
14a30 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
14a40 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
14a50 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
14a60 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
14a70 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
14a80 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
14a90 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
14aa0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
14ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14ac0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
14ad0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
14ae0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
14af0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
14b00 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
14b10 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
14b20 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
14b30 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
14b40 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
14b50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
14b60 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
14b70 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
14b80 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
14b90 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
14ba0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
14bb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14bc0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
14bd0 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
14be0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
14bf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14c00 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
14c10 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
14c20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
14c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
14c40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
14c50 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
14c60 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
14c70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
14c80 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
14c90 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
14ca0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
14cb0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
14cc0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
14cd0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
14ce0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
14cf0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
14d00 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
14d10 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
14d20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
14d30 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
14d40 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
14d50 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
14d60 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
14d70 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
14d80 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
14d90 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
14da0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
14db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14dc0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
14dd0 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
14de0 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
14df0 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
14e00 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
14e10 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
14e20 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
14e30 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
14e40 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
14e50 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
14e60 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
14e70 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
14e80 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
14e90 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
14ea0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
14eb0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
14ec0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
14ed0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
14ee0 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
14ef0 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
14f00 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
14f10 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
14f20 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
14f30 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
14f40 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
14f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
14f60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
14f70 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
14f80 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
14f90 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
14fa0 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
14fb0 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
14fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14fd0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
14fe0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
14ff0 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65  ^As of SQLite ve
15000 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69  rsion 3.7.7, thi
15010 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65  s routines.** re
15020 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69  cords the last i
15030 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62  nsert rowid of b
15040 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62  oth ordinary tab
15050 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c  les and [virtual
15060 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66   tables]..** ^If
15070 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
15080 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65  INSERT]s.** have
15090 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
150a0 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
150b0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
150c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
150d0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
150e0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
150f0 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
15100 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
15110 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
15120 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
15130 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
15140 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
15150 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
15160 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
15170 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
15180 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
15190 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
151a0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
151b0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
151c0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
151d0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
151e0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
151f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
15200 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
15210 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
15220 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
15230 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
15240 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
15250 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
15260 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
15270 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
15280 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
15290 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
152a0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
152b0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
152c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
152d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
152e0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
152f0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
15300 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
15310 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
15320 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
15330 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
15340 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
15350 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
15360 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
15370 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
15380 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
15390 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
153a0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
153b0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
153c0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
153d0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
153e0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
153f0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
15400 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
15410 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
15420 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
15430 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
15440 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
15450 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
15460 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
15470 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
15480 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
15490 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
154a0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
154b0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
154c0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
154d0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
154e0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
154f0 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
15500 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
15510 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
15520 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
15530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15540 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
15550 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
15560 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
15570 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
15580 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
15590 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
155a0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
155b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
155c0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
155d0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
155e0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
155f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
15600 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
15610 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
15620 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
15630 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
15640 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
15650 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
15660 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
15670 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
15680 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
15690 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
156a0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
156b0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
156c0 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
156d0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
156e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
156f0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
15700 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
15710 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
15720 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
15730 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
15740 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
15750 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
15760 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
15770 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
15780 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
15790 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
157a0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
157b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
157c0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
157d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
157e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
157f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
15800 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
15810 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
15820 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
15830 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
15840 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
15850 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
15860 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
15870 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
15880 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
15890 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
158a0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
158b0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
158c0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
158d0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
158e0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
158f0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
15900 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
15910 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
15920 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
15930 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
15940 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
15950 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
15960 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
15970 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
15980 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
15990 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
159a0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
159b0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
159c0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
159d0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
159e0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
159f0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
15a00 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
15a10 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
15a20 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
15a30 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
15a40 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
15a50 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
15a60 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
15a70 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
15a80 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
15a90 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
15aa0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
15ab0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
15ac0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
15ad0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
15ae0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
15af0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
15b00 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
15b10 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
15b20 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
15b30 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
15b40 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
15b50 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
15b60 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
15b70 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
15b80 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
15b90 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
15ba0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
15bb0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
15bc0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
15bd0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
15be0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
15bf0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
15c00 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
15c10 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
15c20 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
15c30 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
15c40 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
15c50 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
15c60 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
15c70 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
15c80 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
15c90 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
15ca0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
15cb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
15cc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15cd0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
15ce0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
15cf0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
15d00 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
15d10 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
15d20 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
15d30 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
15d40 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
15d50 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
15d60 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
15d70 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
15d80 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
15d90 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
15da0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
15db0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
15dc0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
15dd0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
15de0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
15df0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
15e00 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
15e10 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
15e20 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
15e30 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
15e40 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
15e50 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
15e60 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
15e70 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
15e80 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
15e90 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
15ea0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
15eb0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
15ec0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
15ed0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
15ee0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
15ef0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15f00 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
15f10 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
15f20 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
15f30 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
15f40 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
15f50 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
15f60 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
15f70 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
15f80 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
15f90 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
15fa0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
15fb0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
15fc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
15fd0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
15fe0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
15ff0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
16000 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
16010 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
16020 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
16030 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
16040 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
16050 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
16060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16070 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
16080 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
16090 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
160a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
160b0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
160c0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
160d0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
160e0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
160f0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
16100 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
16110 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
16120 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
16130 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
16140 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16150 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
16160 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
16170 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
16180 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
16190 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
161a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
161b0 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
161c0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
161d0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
161e0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
161f0 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
16200 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
16210 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
16220 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
16230 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
16240 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
16250 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
16260 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
16270 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
16280 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
16290 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
162a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
162b0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
162c0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
162d0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
162e0 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
162f0 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
16300 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
16310 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
16320 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
16330 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
16340 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
16350 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
16360 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
16370 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
16380 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
16390 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
163a0 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
163b0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
163c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
163d0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
163e0 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
163f0 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
16400 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
16410 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
16420 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
16430 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
16440 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
16450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
16460 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
16470 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
16480 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
16490 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
164a0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
164b0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
164c0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
164d0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
164e0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
164f0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
16500 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
16510 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
16520 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
16530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16540 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
16550 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
16560 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
16570 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
16580 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
16590 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
165a0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
165b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
165c0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
165d0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
165e0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
165f0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
16600 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
16610 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
16620 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
16630 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
16640 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
16650 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
16660 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
16670 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
16680 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
16690 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
166a0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
166b0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
166c0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
166d0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
166e0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
166f0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
16700 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
16710 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
16720 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
16730 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
16740 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
16750 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
16760 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
16770 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
16780 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
16790 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
167a0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
167b0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
167c0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
167d0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
167e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
167f0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
16800 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
16810 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
16820 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
16830 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
16840 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
16850 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
16860 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
16870 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
16880 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
16890 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
168a0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
168b0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
168c0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
168d0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
168e0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
168f0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
16900 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
16910 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
16920 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
16930 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
16940 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
16950 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
16960 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
16970 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16980 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
16990 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
169a0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
169b0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
169c0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
169d0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
169e0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
169f0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
16a00 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
16a10 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
16a20 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
16a30 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
16a40 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
16a50 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
16a60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
16a70 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
16a80 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
16a90 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
16aa0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
16ab0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16ac0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
16ad0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
16ae0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
16af0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
16b00 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
16b10 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
16b20 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
16b30 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
16b40 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
16b50 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
16b60 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
16b70 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
16b80 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
16b90 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
16ba0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
16bb0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
16bc0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
16bd0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
16be0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
16bf0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
16c00 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
16c10 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
16c20 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
16c30 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
16c40 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
16c50 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
16c60 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
16c70 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
16c80 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
16c90 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
16ca0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
16cb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16cc0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
16cd0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
16ce0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
16cf0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
16d00 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
16d10 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
16d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
16d30 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
16d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d50 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
16d60 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
16d70 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
16d80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
16d90 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
16da0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
16db0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
16dc0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
16dd0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
16de0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
16df0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
16e00 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
16e10 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
16e20 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
16e30 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
16e40 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
16e50 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
16e60 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
16e70 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
16e80 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
16e90 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
16ea0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
16eb0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
16ec0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
16ed0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
16ee0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
16ef0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
16f00 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
16f10 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
16f20 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
16f30 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
16f40 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
16f50 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
16f60 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
16f70 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
16f80 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
16f90 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
16fa0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
16fb0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
16fc0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
16fd0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
16fe0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
16ff0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
17000 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
17010 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
17020 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
17030 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
17040 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
17050 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
17060 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
17070 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
17080 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
17090 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
170a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
170b0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
170c0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
170d0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
170e0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
170f0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
17100 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
17110 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
17120 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
17130 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
17140 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
17150 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
17160 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
17170 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
17180 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
17190 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
171a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
171b0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
171c0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
171d0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
171e0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
171f0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
17200 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
17210 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
17220 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
17230 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
17240 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
17250 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
17260 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
17270 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
17280 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
17290 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
172a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
172b0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
172c0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
172d0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
172e0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
172f0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
17300 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
17310 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
17320 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
17330 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
17340 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
17350 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
17360 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
17370 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
17380 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
17390 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
173a0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
173b0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
173c0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
173d0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
173e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
173f0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
17400 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
17410 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
17420 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
17430 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
17440 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
17450 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
17460 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
17470 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
17480 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
17490 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
174a0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
174b0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
174c0 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
174d0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
174e0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
174f0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
17500 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
17510 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
17520 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
17530 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
17540 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
17550 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
17560 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
17570 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
17580 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
17590 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
175a0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
175b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
175c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
175d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
175e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
175f0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
17600 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
17610 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
17620 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17630 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
17640 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
17650 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
17660 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
17670 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
17680 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
17690 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
176a0 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
176b0 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
176c0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
176d0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
176e0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
176f0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
17700 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
17710 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
17720 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
17730 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
17740 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
17750 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
17760 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
17770 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
17780 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
17790 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
177a0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
177b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
177c0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
177d0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
177e0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
177f0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
17800 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
17810 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
17820 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
17830 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
17840 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
17850 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
17860 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
17870 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
17880 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
17890 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
178a0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
178b0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
178c0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
178d0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
178e0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
178f0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
17900 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17910 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
17920 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
17930 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
17940 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
17950 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
17960 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
17970 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
17980 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
17990 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
179a0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
179b0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
179c0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
179d0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
179e0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
179f0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
17a00 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
17a10 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
17a20 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
17a30 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
17a40 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
17a50 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
17a60 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
17a70 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
17a80 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
17a90 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
17aa0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
17ab0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
17ac0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
17ad0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
17ae0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
17af0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
17b00 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
17b10 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
17b20 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
17b30 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
17b40 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
17b50 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
17b60 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
17b70 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
17b80 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
17b90 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
17ba0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
17bb0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
17bc0 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
17bd0 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
17be0 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
17bf0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
17c00 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
17c10 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
17c20 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
17c30 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
17c40 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
17c50 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
17c60 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
17c70 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
17c80 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
17c90 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
17ca0 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
17cb0 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
17cc0 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
17cd0 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
17ce0 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
17cf0 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
17d00 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
17d10 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
17d20 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
17d30 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
17d40 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
17d50 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
17d60 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
17d70 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
17d80 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
17d90 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
17da0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
17db0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
17dc0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
17dd0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
17de0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
17df0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
17e00 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
17e10 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
17e20 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
17e30 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
17e40 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
17e50 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
17e60 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
17e70 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
17e80 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
17e90 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
17ea0 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
17eb0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
17ec0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
17ed0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
17ee0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
17ef0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
17f00 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
17f10 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
17f20 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
17f30 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
17f40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
17f50 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
17f60 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
17f70 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
17f80 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
17f90 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
17fa0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
17fb0 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
17fc0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
17fd0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
17fe0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
17ff0 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
18000 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
18010 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
18020 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
18030 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
18040 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
18050 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
18060 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18070 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
18080 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18090 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
180a0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
180b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
180c0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
180d0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
180e0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
180f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18100 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
18110 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
18120 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
18130 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
18140 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
18150 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
18160 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
18170 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
18180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
18190 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
181a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
181b0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
181c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
181d0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
181e0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
181f0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
18200 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
18210 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
18220 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
18230 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
18240 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
18250 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
18260 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
18270 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
18280 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
18290 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
182a0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
182b0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
182c0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
182d0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
182e0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
182f0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
18300 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
18310 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
18320 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
18330 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
18340 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
18350 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
18360 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
18370 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
18380 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
18390 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
183a0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
183b0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
183c0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
183d0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
183e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
183f0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
18400 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
18410 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
18420 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
18430 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
18440 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
18450 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
18460 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
18470 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
18480 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
18490 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
184a0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
184b0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
184c0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
184d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
184e0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
184f0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
18500 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
18510 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
18520 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
18530 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
18540 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
18550 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
18560 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18570 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
18580 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
18590 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
185a0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
185b0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
185c0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
185d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
185e0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
185f0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
18600 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
18610 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
18620 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
18630 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
18640 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
18650 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
18660 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
18670 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
18680 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
18690 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
186a0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
186b0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
186c0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
186d0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
186e0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
186f0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
18700 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
18710 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
18720 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
18730 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
18740 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
18750 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
18760 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
18770 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
18780 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
18790 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
187a0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
187b0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
187c0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
187d0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
187e0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
187f0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
18800 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
18810 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
18820 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
18830 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
18840 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
18850 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
18860 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
18870 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
18880 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
18890 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
188a0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
188b0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
188c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
188d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
188e0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
188f0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
18900 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
18910 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18920 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
18930 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
18940 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
18950 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
18960 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
18970 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
18980 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
18990 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
189a0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
189b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
189c0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
189d0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
189e0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
189f0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
18a00 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
18a10 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18a20 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
18a30 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
18a40 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
18a50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18a60 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
18a70 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
18a80 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
18a90 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
18aa0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
18ab0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
18ac0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
18ad0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
18ae0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
18af0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
18b00 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
18b10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
18b20 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
18b30 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
18b40 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
18b50 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
18b60 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
18b70 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
18b80 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
18b90 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
18ba0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
18bb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
18bc0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
18bd0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
18be0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
18bf0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
18c00 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
18c10 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
18c20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
18c30 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
18c40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18c50 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
18c60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18c70 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
18c80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18c90 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
18ca0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
18cb0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
18cc0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
18cd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
18ce0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18cf0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
18d00 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
18d10 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
18d20 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
18d30 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
18d40 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
18d50 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
18d60 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
18d70 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
18d80 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
18d90 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
18da0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
18db0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
18dc0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
18dd0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
18de0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
18df0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
18e00 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
18e10 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
18e20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
18e30 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
18e40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
18e50 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
18e60 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
18e70 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
18e80 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
18e90 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
18ea0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
18eb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
18ec0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
18ed0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
18ee0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
18ef0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
18f00 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
18f10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
18f20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
18f30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
18f40 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
18f50 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
18f60 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
18f70 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
18f80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
18f90 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
18fa0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
18fb0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
18fc0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
18fd0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
18fe0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
18ff0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
19000 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
19010 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
19020 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
19030 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
19040 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
19050 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
19060 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
19070 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
19080 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
19090 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
190a0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
190b0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
190c0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
190d0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
190e0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
190f0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
19100 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
19110 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
19120 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
19130 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
19140 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19150 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
19160 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
19170 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
19180 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
19190 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
191a0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
191b0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
191c0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
191d0 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
191e0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
191f0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
19200 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
19210 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
19220 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
19230 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
19240 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
19250 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
19260 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
19270 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
19280 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
19290 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
192a0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
192b0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
192c0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
192d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
192e0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
192f0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
19300 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
19310 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
19320 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
19330 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
19340 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
19350 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
19360 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
19370 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19380 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
19390 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
193a0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
193b0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
193c0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
193d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
193e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
193f0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
19400 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
19410 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
19420 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
19430 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
19440 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
19450 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
19460 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
19470 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
19480 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
19490 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
194a0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
194b0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
194c0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
194d0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
194e0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
194f0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
19500 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
19510 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
19520 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
19530 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
19540 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
19550 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
19560 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
19570 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
19580 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
19590 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
195a0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
195b0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
195c0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
195d0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
195e0 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
195f0 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
19600 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
19610 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
19620 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
19630 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
19640 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
19650 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
19660 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
19670 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
19680 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
19690 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
196a0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
196b0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
196c0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
196d0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
196e0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
196f0 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
19700 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
19710 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
19720 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
19730 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
19740 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
19750 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
19760 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
19770 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
19780 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
19790 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
197a0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
197b0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
197c0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
197d0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
197e0 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
197f0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
19800 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
19810 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
19820 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
19830 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
19840 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
19850 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
19860 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
19870 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
19880 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
19890 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
198a0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
198b0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
198c0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
198d0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
198e0 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
198f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19900 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
19910 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
19920 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
19930 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
19940 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
19950 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
19960 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
19970 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
19980 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
19990 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
199a0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
199b0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
199c0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
199d0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
199e0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
199f0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
19a00 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
19a10 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
19a20 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
19a30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
19a40 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
19a50 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
19a60 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
19a70 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
19a80 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
19a90 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
19aa0 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
19ab0 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
19ac0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
19ad0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
19ae0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
19af0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
19b00 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
19b10 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
19b20 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
19b30 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
19b40 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
19b50 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
19b60 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
19b70 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
19b80 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
19b90 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
19ba0 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
19bb0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
19bc0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
19bd0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
19be0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
19bf0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
19c00 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19c10 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
19c20 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
19c30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19c40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
19c50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19c60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
19c70 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
19c80 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
19c90 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
19ca0 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
19cb0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
19cc0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
19cd0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
19ce0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
19cf0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19d00 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
19d10 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
19d20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
19d30 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
19d40 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
19d50 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
19d60 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
19d70 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
19d80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
19d90 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
19da0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
19db0 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
19dc0 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
19dd0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
19de0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
19df0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
19e00 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
19e10 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
19e20 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
19e30 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
19e40 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
19e50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19e60 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
19e70 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
19e80 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
19e90 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
19ea0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
19eb0 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
19ec0 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
19ed0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
19ee0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
19ef0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
19f00 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
19f10 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
19f20 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
19f30 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
19f40 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
19f50 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
19f60 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
19f70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
19f80 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
19f90 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
19fa0 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
19fb0 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
19fc0 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
19fd0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
19fe0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
19ff0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1a000 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1a010 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1a020 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1a030 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1a040 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1a050 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1a060 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a070 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1a080 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1a090 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1a0a0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1a0b0 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1a0c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1a0d0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1a0e0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1a0f0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1a100 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a110 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1a120 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1a130 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1a140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1a150 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1a160 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1a170 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1a180 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1a190 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1a1a0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1a1b0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1a1c0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1a1d0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1a1e0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1a1f0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1a200 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1a210 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1a220 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1a230 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1a240 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1a250 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1a260 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1a270 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1a280 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1a290 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1a2a0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1a2b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1a2c0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1a2d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1a2e0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1a2f0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1a300 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a310 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1a320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1a330 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1a340 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1a350 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1a360 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1a370 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1a380 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1a390 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1a3a0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1a3b0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1a3c0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1a3d0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1a3e0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1a3f0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1a400 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1a410 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1a420 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1a430 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1a440 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1a450 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1a460 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1a470 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1a480 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1a490 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1a4a0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1a4b0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1a4c0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1a4d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1a4e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1a4f0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1a500 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1a510 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1a520 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1a530 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a540 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1a550 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1a560 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1a570 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1a580 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1a590 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1a5a0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1a5b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1a5c0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1a5d0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1a5e0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1a5f0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1a600 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1a610 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1a620 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1a630 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1a640 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1a650 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1a660 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1a670 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1a680 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1a690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1a6a0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1a6b0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1a6c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1a6d0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1a6e0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1a6f0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1a700 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1a710 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1a720 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1a730 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1a740 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1a750 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1a760 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1a770 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1a780 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1a790 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1a7a0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1a7b0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1a7c0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1a7d0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1a7e0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1a7f0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1a800 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1a810 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1a820 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1a830 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1a840 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1a850 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1a860 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
1a870 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1a880 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1a890 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1a8a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
1a8b0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
1a8c0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
1a8d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1a8e0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
1a8f0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
1a900 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
1a910 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
1a920 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
1a930 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1a940 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a950 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1a960 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1a970 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1a980 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1a990 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1a9a0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
1a9b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a9c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1a9d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
1a9e0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
1a9f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1aa00 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
1aa10 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1aa20 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1aa30 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1aa40 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1aa50 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1aa60 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
1aa70 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
1aa80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1aa90 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1aaa0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1aab0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1aac0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1aad0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1aae0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1aaf0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1ab00 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
1ab10 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
1ab20 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1ab30 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1ab40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ab50 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1ab60 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1ab70 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ab80 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1ab90 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1aba0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1abb0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1abc0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
1abd0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1abe0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1abf0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1ac00 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1ac10 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1ac20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1ac30 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
1ac40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1ac50 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1ac60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ac70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1ac80 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
1ac90 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1aca0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1acb0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1acc0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1acd0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1ace0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1acf0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1ad00 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1ad10 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1ad20 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1ad30 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1ad40 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1ad50 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1ad60 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1ad70 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1ad80 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1ad90 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1ada0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1adb0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1adc0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1add0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1ade0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1adf0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1ae00 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1ae10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1ae20 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1ae30 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1ae40 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1ae50 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1ae60 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1ae70 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1ae80 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1ae90 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1aea0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1aeb0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1aec0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1aed0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1aee0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1aef0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1af00 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1af10 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1af20 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1af30 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1af40 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1af50 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1af60 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1af70 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1af80 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1af90 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1afa0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1afb0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1afc0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1afd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1afe0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1aff0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b000 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1b010 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1b020 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1b030 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1b040 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1b050 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1b060 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1b070 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1b080 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b090 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1b0a0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1b0b0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1b0c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1b0d0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1b0e0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1b0f0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1b100 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1b110 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1b120 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1b130 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1b140 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1b150 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1b160 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1b170 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1b180 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1b190 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1b1a0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1b1b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1b1c0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1b1d0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1b1e0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1b1f0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1b200 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1b210 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1b220 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1b230 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1b240 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1b250 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1b260 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1b270 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1b280 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1b290 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1b2a0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1b2b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1b2c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1b2d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1b2e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1b2f0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1b300 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1b310 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1b320 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1b330 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1b340 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1b350 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1b360 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1b370 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1b380 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1b390 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1b3a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1b3b0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1b3c0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1b3d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1b3e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1b3f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1b400 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1b410 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1b420 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1b430 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1b440 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1b450 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1b460 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1b470 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1b480 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1b490 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1b4a0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1b4b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1b4c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1b4d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1b4e0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1b4f0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1b500 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1b510 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1b520 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1b530 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1b540 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1b550 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1b560 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1b570 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1b580 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1b590 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1b5a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1b5b0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1b5c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1b5d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1b5e0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1b5f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1b600 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1b610 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1b620 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1b630 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1b640 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1b650 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1b660 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1b670 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1b680 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1b690 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1b6a0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1b6b0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1b6c0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1b6d0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1b6e0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1b6f0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1b700 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1b710 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1b720 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1b730 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1b740 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1b750 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1b760 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1b770 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1b780 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1b790 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1b7a0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1b7b0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1b7c0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1b7d0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1b7e0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1b7f0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1b800 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1b810 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1b820 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1b830 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1b840 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1b850 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1b860 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1b870 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1b880 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1b890 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1b8a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1b8b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1b8c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1b8d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1b8e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1b8f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b900 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1b910 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1b920 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1b930 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1b940 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1b950 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1b960 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1b970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1b980 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1b990 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1b9a0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1b9b0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1b9c0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1b9d0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1b9e0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1b9f0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1ba00 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1ba10 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1ba20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ba30 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1ba40 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1ba50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1ba60 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1ba70 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1ba80 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1ba90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1baa0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1bab0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1bac0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1bad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1bae0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1baf0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1bb00 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1bb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1bb20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1bb30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1bb40 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1bb50 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1bb60 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1bb70 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1bb80 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1bb90 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1bba0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1bbb0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1bbc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1bbd0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1bbe0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1bbf0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1bc00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1bc10 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1bc20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1bc30 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1bc40 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1bc50 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1bc60 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1bc70 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1bc80 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1bc90 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1bca0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1bcb0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1bcc0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1bcd0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1bce0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1bcf0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1bd00 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1bd10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1bd20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1bd30 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1bd40 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1bd50 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1bd60 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1bd70 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1bd80 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1bd90 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1bda0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1bdb0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1bdc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1bdd0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1bde0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1bdf0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1be00 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1be10 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1be20 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1be30 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1be40 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1be50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1be60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1be70 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1be80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1be90 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1bea0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1beb0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1bec0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1bed0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1bee0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1bef0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1bf00 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1bf10 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1bf20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1bf30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1bf40 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1bf50 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1bf60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1bf70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1bf80 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1bf90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1bfa0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1bfb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1bfc0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1bfd0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1bfe0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1bff0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1c000 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1c010 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1c020 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1c030 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1c040 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1c050 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1c060 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1c070 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1c080 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1c090 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1c0a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1c0b0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1c0c0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1c0d0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1c0e0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1c0f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1c100 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1c110 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1c120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1c130 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1c140 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1c150 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1c160 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1c170 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1c180 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1c190 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1c1a0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1c1b0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1c1c0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1c1d0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1c1e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1c1f0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1c200 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1c210 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1c220 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1c230 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1c240 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1c250 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1c260 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1c270 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1c280 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1c290 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1c2a0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1c2b0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1c2c0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1c2d0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1c2e0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1c2f0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1c300 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1c310 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1c320 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1c330 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1c340 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1c350 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1c360 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1c370 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1c380 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1c390 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1c3a0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1c3b0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1c3c0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1c3d0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1c3e0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1c3f0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1c400 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1c410 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1c420 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1c430 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1c440 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1c450 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1c460 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1c470 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1c480 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1c490 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1c4a0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1c4b0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1c4c0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1c4d0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1c4e0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1c4f0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1c500 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1c510 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1c520 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1c530 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1c540 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1c550 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1c560 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1c570 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1c580 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1c590 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1c5a0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1c5b0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1c5c0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1c5d0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1c5e0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1c5f0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1c600 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1c610 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1c620 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1c630 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1c640 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1c650 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1c660 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1c670 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1c680 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1c690 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1c6a0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1c6b0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1c6c0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1c6d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1c6e0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1c6f0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1c700 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1c710 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1c720 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1c730 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1c740 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1c750 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1c760 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1c770 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1c780 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1c790 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1c7a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c7b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1c7c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1c7d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1c7e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c7f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1c800 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c810 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1c820 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1c830 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1c840 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1c850 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1c860 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1c870 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1c880 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1c890 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1c8a0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1c8b0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1c8c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1c8d0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1c8e0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1c8f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1c900 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1c910 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1c920 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1c930 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1c940 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1c950 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c960 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1c970 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1c980 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1c990 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1c9a0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1c9b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1c9c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1c9d0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1c9e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1c9f0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1ca00 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1ca10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1ca20 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1ca30 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1ca40 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1ca50 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1ca60 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1ca70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1ca80 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1ca90 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1caa0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1cab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1cac0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1cad0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1cae0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1caf0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1cb00 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1cb10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1cb20 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1cb30 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1cb40 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1cb50 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1cb60 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1cb70 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1cb80 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1cb90 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1cba0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1cbb0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1cbc0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1cbd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1cbe0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1cbf0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1cc00 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1cc10 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1cc20 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1cc30 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1cc40 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1cc50 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1cc60 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1cc70 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1cc80 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1cc90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1cca0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1ccb0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1ccc0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1ccd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1cce0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1ccf0 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1cd00 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1cd10 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1cd20 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1cd30 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1cd40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1cd50 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1cd60 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1cd70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1cd80 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1cd90 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1cda0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1cdb0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1cdc0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1cdd0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1cde0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1cdf0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1ce00 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1ce10 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1ce20 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1ce30 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1ce40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1ce50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1ce60 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1ce70 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1ce80 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1ce90 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1cea0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1ceb0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1cec0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1ced0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1cee0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1cef0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1cf00 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1cf10 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1cf20 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1cf30 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1cf40 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1cf50 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1cf60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1cf70 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1cf80 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1cf90 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1cfa0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1cfb0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1cfc0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1cfd0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1cfe0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1cff0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1d000 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1d010 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1d020 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1d030 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1d040 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1d050 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1d060 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1d070 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1d080 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1d090 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1d0a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d0b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1d0c0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1d0d0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1d0e0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1d0f0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1d100 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1d110 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d120 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1d130 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1d140 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1d150 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1d160 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1d170 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1d180 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1d190 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1d1a0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1d1b0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1d1c0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1d1d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d1e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d1f0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1d200 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1d210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1d220 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1d230 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1d240 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1d250 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1d260 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d270 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d280 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1d290 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d2a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d2b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d2c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1d2d0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1d2e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1d2f0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1d300 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d310 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1d320 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1d330 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1d340 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d350 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d360 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1d370 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1d380 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1d390 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d3a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d3b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1d3c0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1d3d0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1d3e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d3f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d400 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1d410 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1d420 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1d430 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d440 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d450 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1d460 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1d470 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1d480 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d490 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d4a0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1d4b0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1d4c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1d4d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d4e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d4f0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1d500 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1d510 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1d520 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1d530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d540 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1d550 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1d560 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1d570 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d590 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1d5a0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1d5b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1d5c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1d5d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1d5e0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1d5f0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1d600 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d610 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1d630 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1d640 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1d650 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1d660 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d670 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d680 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1d690 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1d6a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1d6b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d6c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d6d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1d6e0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1d6f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1d700 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1d710 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1d720 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1d730 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1d740 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1d750 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d760 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1d770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1d780 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d790 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d7a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d7b0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1d7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1d7d0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1d7e0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1d7f0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1d800 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1d810 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1d820 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1d830 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1d840 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d850 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1d860 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1d870 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1d880 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d890 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d8a0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1d8b0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1d8c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1d8d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d8e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d8f0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1d900 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1d910 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d920 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1d930 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d940 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1d950 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1d960 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1d970 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d980 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d990 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1d9a0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1d9b0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1d9c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d9d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d9e0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1d9f0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1da00 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1da10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1da20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1da30 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1da40 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1da50 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1da60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1da70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1da80 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1da90 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1daa0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1dab0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1dad0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1dae0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1daf0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1db00 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1db10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1db20 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1db30 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1db40 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1db50 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1db60 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1db70 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1db80 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1db90 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1dba0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1dbb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1dbc0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1dbd0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1dbe0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1dbf0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1dc00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1dc10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dc20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1dc30 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1dc40 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1dc50 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1dc60 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1dc70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1dc80 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1dc90 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1dca0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1dcb0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1dcc0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1dcd0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1dce0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1dcf0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1dd00 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1dd10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1dd20 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1dd30 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1dd40 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1dd50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1dd60 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1dd70 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1dd80 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1dd90 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1dda0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1ddb0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1ddc0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1ddd0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1dde0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1ddf0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1de00 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1de10 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1de20 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1de30 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1de40 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1de50 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1de60 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1de70 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1de80 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1de90 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1dea0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1deb0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1dec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1ded0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1dee0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1def0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1df00 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1df10 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1df20 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1df30 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1df40 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1df50 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1df60 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1df70 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1df80 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1df90 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1dfa0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1dfb0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1dfc0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1dfd0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1dfe0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1dff0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1e000 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1e010 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1e020 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1e030 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1e040 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1e050 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1e060 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1e070 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1e080 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1e090 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1e0a0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1e0b0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1e0c0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1e0d0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1e0e0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1e0f0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1e100 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1e110 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1e120 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1e130 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1e140 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1e150 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1e160 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1e170 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1e180 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1e190 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1e1a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1e1b0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1e1c0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1e1d0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1e1e0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1e1f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1e200 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1e210 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1e220 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1e230 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1e240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e250 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1e260 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1e270 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1e280 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1e290 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1e2a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1e2b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1e2c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1e2d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1e2e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1e2f0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1e300 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1e310 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1e320 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1e330 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1e340 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1e350 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1e360 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1e370 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1e380 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1e390 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1e3a0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1e3b0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1e3c0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1e3d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1e3e0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1e3f0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1e400 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1e410 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1e420 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1e430 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1e440 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1e450 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1e460 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1e470 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1e480 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1e490 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1e4a0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1e4b0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1e4c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1e4d0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1e4e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1e4f0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1e500 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1e510 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1e520 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1e530 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1e540 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1e550 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1e560 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1e570 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1e580 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1e590 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1e5a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1e5b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1e5c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1e5d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1e5e0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1e5f0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1e600 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1e610 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1e620 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1e630 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1e640 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1e650 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1e660 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1e670 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1e680 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1e690 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e6a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1e6b0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1e6c0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1e6d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1e6e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1e6f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1e700 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1e710 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1e720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1e730 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1e740 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1e750 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1e760 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1e770 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1e780 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1e790 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1e7a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1e7b0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1e7c0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1e7d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1e7e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1e7f0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1e800 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1e810 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1e820 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1e830 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1e840 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1e850 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1e860 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1e870 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1e880 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e890 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1e8a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1e8b0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1e8c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1e8d0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1e8e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1e8f0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1e900 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1e910 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1e920 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1e930 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1e940 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1e950 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1e960 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1e970 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1e980 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1e990 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1e9a0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1e9b0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1e9c0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1e9d0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1e9e0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1e9f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1ea00 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1ea10 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1ea20 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1ea30 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1ea40 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1ea50 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1ea60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1ea70 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1ea80 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1ea90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1eaa0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1eab0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1eac0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1ead0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1eae0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1eaf0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1eb00 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1eb10 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1eb20 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1eb30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1eb40 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1eb50 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1eb60 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1eb70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1eb80 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1eb90 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1eba0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1ebb0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1ebc0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1ebd0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1ebe0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1ebf0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1ec00 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1ec10 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1ec20 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1ec30 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1ec40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ec50 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1ec60 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1ec70 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1ec80 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1ec90 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1eca0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1ecb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ecc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1ecd0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1ece0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1ecf0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1ed00 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1ed10 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1ed20 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1ed30 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1ed40 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1ed50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1ed60 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1ed70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1ed80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ed90 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1eda0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1edb0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1edc0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1edd0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1ede0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1edf0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1ee00 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1ee10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1ee20 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1ee30 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1ee40 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1ee50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1ee60 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1ee70 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1ee80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1ee90 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1eea0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1eeb0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1eec0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1eed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1eee0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1eef0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1ef00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1ef10 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1ef20 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1ef30 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1ef40 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1ef50 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1ef60 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1ef70 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1ef80 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1ef90 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1efa0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1efb0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1efc0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1efd0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1efe0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1eff0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1f000 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1f010 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1f020 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1f030 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1f040 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1f050 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1f060 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1f070 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1f080 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1f090 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1f0a0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1f0b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1f0c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1f0d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1f0e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1f0f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1f100 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1f110 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1f120 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1f130 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1f140 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1f150 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1f160 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1f170 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1f180 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1f190 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1f1a0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1f1b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f1c0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1f1d0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1f1e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1f1f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1f200 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1f210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1f220 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1f230 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1f240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f250 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1f260 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1f270 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1f280 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1f290 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1f2a0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1f2b0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1f2c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1f2d0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1f2e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1f2f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1f300 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1f310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f320 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1f330 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1f340 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1f350 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1f360 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1f370 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1f380 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1f390 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1f3a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1f3b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1f3c0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1f3d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f3e0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1f3f0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1f400 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1f410 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1f420 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1f430 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1f440 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1f450 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1f460 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1f470 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1f480 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1f490 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1f4a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f4b0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1f4c0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1f4d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1f4e0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1f4f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1f500 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1f510 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f520 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1f530 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1f540 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1f550 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1f560 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1f570 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1f580 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1f590 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1f5a0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1f5b0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1f5c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1f5d0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1f5e0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1f5f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1f600 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1f610 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1f620 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1f630 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1f640 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1f650 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1f660 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1f670 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1f680 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
1f690 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1f6a0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1f6b0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1f6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1f6d0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1f6e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1f6f0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1f700 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1f710 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1f720 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1f730 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1f740 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1f750 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1f760 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1f770 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1f780 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1f790 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1f7a0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1f7b0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1f7c0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1f7d0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1f7e0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1f7f0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
1f800 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1f810 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1f820 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1f830 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1f840 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1f850 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1f860 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
1f870 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1f880 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1f890 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1f8a0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1f8b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1f8c0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1f8d0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
1f8e0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
1f8f0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
1f900 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
1f910 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
1f920 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
1f930 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
1f940 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
1f950 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
1f960 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
1f970 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
1f980 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
1f990 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
1f9a0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
1f9b0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1f9c0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
1f9d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1f9e0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
1f9f0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1fa00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1fa10 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
1fa20 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
1fa30 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
1fa40 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
1fa50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
1fa60 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
1fa70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
1fa80 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
1fa90 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
1faa0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
1fab0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1fac0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1fad0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
1fae0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1faf0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
1fb00 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
1fb10 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
1fb20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1fb30 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
1fb40 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
1fb50 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
1fb60 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
1fb70 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
1fb80 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
1fb90 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1fba0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
1fbb0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
1fbc0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
1fbd0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
1fbe0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
1fbf0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
1fc00 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
1fc10 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
1fc20 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
1fc30 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
1fc40 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
1fc50 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
1fc60 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
1fc70 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
1fc80 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
1fc90 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
1fca0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
1fcb0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
1fcc0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
1fcd0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
1fce0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
1fcf0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
1fd00 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
1fd10 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
1fd20 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
1fd30 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
1fd40 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
1fd50 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
1fd60 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
1fd70 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
1fd80 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
1fd90 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
1fda0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
1fdb0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
1fdc0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
1fdd0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
1fde0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
1fdf0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
1fe00 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
1fe10 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
1fe20 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
1fe30 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
1fe40 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
1fe50 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
1fe60 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
1fe70 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
1fe80 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
1fe90 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
1fea0 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
1feb0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
1fec0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
1fed0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
1fee0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
1fef0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
1ff00 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
1ff10 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
1ff20 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
1ff30 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
1ff40 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
1ff50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
1ff60 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
1ff70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
1ff80 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
1ff90 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
1ffa0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1ffb0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
1ffc0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
1ffd0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1ffe0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
1fff0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
20000 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
20010 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
20020 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
20030 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
20040 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
20050 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
20060 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
20070 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
20080 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
20090 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
200a0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
200b0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
200c0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
200d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
200e0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
200f0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
20100 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
20110 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
20120 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
20130 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
20140 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
20150 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
20160 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
20170 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
20180 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
20190 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
201a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
201b0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
201c0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
201d0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
201e0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
201f0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
20200 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
20210 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
20220 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
20230 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
20240 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
20250 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
20260 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
20270 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
20280 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
20290 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
202a0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
202b0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
202c0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
202d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
202e0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
202f0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
20300 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
20310 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
20320 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
20330 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
20340 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
20350 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
20360 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20370 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
20380 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
20390 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
203a0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
203b0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
203c0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
203d0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
203e0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
203f0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
20400 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
20410 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
20420 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
20430 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
20440 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
20450 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
20460 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
20470 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
20480 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
20490 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
204a0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
204b0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
204c0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
204d0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
204e0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
204f0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
20500 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
20510 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
20520 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
20530 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
20540 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
20550 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
20560 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
20570 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20580 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
20590 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
205a0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
205b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
205c0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
205d0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
205e0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
205f0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
20600 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
20610 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
20620 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
20630 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20640 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
20650 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
20660 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
20670 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
20680 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
20690 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
206a0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
206b0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
206c0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
206d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
206e0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
206f0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
20700 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
20710 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
20720 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
20730 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
20740 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
20750 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
20760 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
20770 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  ur requested by 
20780 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
20790 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
207a0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
207b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
207c0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
207d0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
207e0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
207f0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
20800 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
20810 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
20820 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
20830 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20840 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
20850 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
20860 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
20870 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
20880 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
20890 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
208a0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
208b0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
208c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
208d0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
208e0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
208f0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
20900 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
20910 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
20920 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
20930 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
20940 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
20950 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
20960 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
20970 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
20980 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
20990 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
209a0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
209b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
209c0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
209d0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
209e0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
209f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
20a00 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
20a10 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
20a20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
20a30 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
20a40 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
20a50 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
20a60 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
20a70 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
20a80 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
20a90 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
20aa0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
20ab0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
20ac0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
20ad0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
20ae0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
20af0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
20b00 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
20b10 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
20b20 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
20b30 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
20b40 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
20b50 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
20b60 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
20b70 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
20b80 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
20b90 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
20ba0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
20bb0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
20bc0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
20bd0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
20be0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
20bf0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
20c00 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
20c10 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
20c20 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
20c30 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
20c40 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
20c50 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
20c60 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
20c70 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
20c80 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
20c90 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
20ca0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
20cb0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
20cc0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
20cd0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
20ce0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
20cf0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
20d00 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
20d10 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
20d20 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
20d30 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
20d40 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
20d50 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
20d60 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
20d70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20d80 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
20d90 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
20da0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
20db0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20dc0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
20dd0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
20de0 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
20df0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
20e00 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
20e10 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20e20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
20e30 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
20e40 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
20e50 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
20e60 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
20e70 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
20e80 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20e90 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
20ea0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
20eb0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
20ec0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
20ed0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
20ee0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
20ef0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
20f00 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
20f10 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
20f20 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
20f30 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
20f40 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
20f50 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
20f60 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
20f70 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
20f80 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
20f90 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
20fa0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
20fb0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
20fc0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
20fd0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
20fe0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
20ff0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
21000 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
21010 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
21020 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
21030 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
21040 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
21050 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
21060 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
21070 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
21080 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
21090 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
210a0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
210b0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
210c0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
210d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
210e0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
210f0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21100 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
21110 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
21120 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
21130 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
21140 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
21150 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
21160 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
21170 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
21180 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
21190 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
211a0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
211b0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
211c0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
211d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
211e0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
211f0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
21200 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
21210 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
21220 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
21230 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
21240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21250 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21260 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
21270 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
21280 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
21290 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
212a0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
212b0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
212c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
212d0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
212e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
212f0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
21300 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
21310 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
21320 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
21330 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
21340 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
21350 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
21360 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
21370 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
21380 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
21390 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
213a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
213b0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
213c0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
213d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
213e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
213f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
21400 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
21410 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
21420 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
21430 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
21440 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
21450 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
21460 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
21470 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
21480 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
21490 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
214a0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
214b0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
214c0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
214d0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
214e0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
214f0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
21500 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
21510 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
21520 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
21530 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
21540 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
21550 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
21560 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
21570 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
21580 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
21590 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
215a0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
215b0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
215c0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
215d0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
215e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
215f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
21600 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
21610 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
21620 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
21630 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
21640 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
21650 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
21660 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
21670 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
21680 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
21690 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
216a0 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
216b0 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
216c0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
216d0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
216e0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
216f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
21700 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
21710 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
21720 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
21730 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
21740 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
21750 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
21760 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
21770 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21780 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
21790 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
217a0 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
217b0 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
217c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
217d0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
217e0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
217f0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
21800 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
21810 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
21820 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
21830 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
21840 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
21850 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
21860 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
21870 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
21880 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
21890 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
218a0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
218b0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
218c0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
218d0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
218e0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
218f0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
21900 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
21910 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
21920 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
21930 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
21940 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
21950 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
21960 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
21970 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
21980 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
21990 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
219a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
219b0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
219c0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
219d0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
219e0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
219f0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
21a00 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
21a10 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
21a20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
21a30 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
21a40 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
21a50 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
21a60 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
21a70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
21a80 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
21a90 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
21aa0 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
21ab0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
21ac0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
21ad0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
21ae0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
21af0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
21b00 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
21b10 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
21b20 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
21b30 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
21b40 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
21b50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
21b60 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
21b70 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
21b80 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
21b90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
21ba0 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
21bb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
21bc0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
21bd0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
21be0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
21bf0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
21c00 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
21c10 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
21c20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
21c30 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
21c40 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
21c50 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
21c60 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
21c70 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
21c80 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
21c90 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
21ca0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
21cb0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
21cc0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
21cd0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
21ce0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
21cf0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
21d00 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
21d10 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
21d20 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
21d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
21d40 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
21d50 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
21d60 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
21d70 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
21d80 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
21d90 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
21da0 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
21db0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
21dc0 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
21dd0 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
21de0 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
21df0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
21e00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
21e10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
21e20 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
21e30 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
21e40 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
21e50 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
21e60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
21e70 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
21e80 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
21e90 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
21ea0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21eb0 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
21ec0 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
21ed0 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
21ee0 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
21ef0 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
21f00 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
21f10 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
21f20 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
21f30 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
21f40 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
21f50 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
21f60 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
21f70 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
21f80 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
21f90 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
21fa0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
21fb0 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
21fc0 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
21fd0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
21fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
21ff0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
22000 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
22010 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
22020 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
22030 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
22040 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
22050 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
22060 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
22070 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
22080 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
22090 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
220a0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
220b0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
220c0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
220d0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
220e0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
220f0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
22100 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
22110 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
22120 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
22130 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
22140 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
22150 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
22160 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
22170 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
22180 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
22190 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
221a0 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
221b0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
221c0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
221d0 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
221e0 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
221f0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
22200 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
22210 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
22220 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
22230 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
22240 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
22250 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
22260 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
22270 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
22280 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
22290 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
222a0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
222b0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
222c0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
222d0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
222e0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
222f0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
22300 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
22310 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
22320 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
22330 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
22340 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
22350 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
22360 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
22370 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
22380 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
22390 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
223a0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
223b0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
223c0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
223d0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
223e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
223f0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
22400 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
22410 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
22420 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
22430 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
22440 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
22450 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
22460 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
22470 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
22480 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
22490 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
224a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
224b0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
224c0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
224d0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
224e0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
224f0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
22500 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
22510 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
22520 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
22530 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
22540 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
22550 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
22560 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
22570 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
22580 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
22590 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
225a0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
225b0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
225c0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
225d0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
225e0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
225f0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
22600 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
22610 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
22620 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
22630 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
22640 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
22650 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
22660 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
22670 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
22680 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
22690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
226a0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
226b0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
226c0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
226d0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
226e0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
226f0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
22700 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
22710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22720 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
22730 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
22740 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
22750 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
22760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
22770 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
22780 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
22790 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
227a0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
227b0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
227c0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
227d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
227e0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
227f0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
22800 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
22810 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
22820 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
22830 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
22840 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
22850 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
22860 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
22870 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
22880 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
22890 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
228a0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
228b0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
228c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
228d0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
228e0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
228f0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
22900 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
22910 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
22920 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
22930 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22940 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
22950 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
22960 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
22970 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
22980 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
22990 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
229a0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
229b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
229c0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
229d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
229e0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
229f0 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
22a00 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
22a10 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
22a20 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
22a30 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
22a40 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
22a50 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
22a60 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
22a70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22a80 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
22a90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
22aa0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
22ab0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
22ac0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
22ad0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
22ae0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
22af0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
22b00 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
22b10 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
22b20 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
22b30 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
22b40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
22b50 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
22b60 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
22b70 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
22b80 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
22b90 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
22ba0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
22bb0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
22bc0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
22bd0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
22be0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
22bf0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
22c00 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
22c10 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
22c20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
22c30 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
22c40 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
22c50 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
22c60 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
22c70 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
22c80 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
22c90 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
22ca0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
22cb0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
22cc0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
22cd0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
22ce0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
22cf0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
22d00 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
22d10 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
22d20 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
22d30 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
22d40 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
22d50 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
22d60 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
22d70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
22d80 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
22d90 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
22da0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
22db0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
22dc0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
22dd0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
22de0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
22df0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
22e00 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
22e10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22e20 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
22e30 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
22e40 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
22e50 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
22e60 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
22e70 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
22e80 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
22e90 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
22ea0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
22eb0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
22ec0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
22ed0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
22ee0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
22ef0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
22f00 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
22f10 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
22f20 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
22f30 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
22f40 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
22f50 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
22f60 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
22f70 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
22f80 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
22f90 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
22fa0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
22fb0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
22fc0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
22fd0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
22fe0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
22ff0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
23000 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
23010 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
23020 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
23030 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
23040 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
23050 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
23060 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
23070 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
23080 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
23090 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
230a0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
230b0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
230c0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
230d0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
230e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
230f0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
23100 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
23110 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
23120 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
23130 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
23140 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
23150 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
23160 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
23170 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
23180 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
23190 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
231a0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
231b0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
231c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
231d0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
231e0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
231f0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
23200 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
23210 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
23220 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
23230 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
23240 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
23250 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
23260 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
23270 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
23280 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
23290 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
232a0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
232b0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
232c0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
232d0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
232e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
232f0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
23300 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
23310 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
23320 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
23330 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
23340 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
23350 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
23360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23370 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
23380 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
23390 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
233a0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
233b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
233c0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
233d0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
233e0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
233f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23400 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
23410 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
23420 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
23430 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23440 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
23450 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23460 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
23470 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23480 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
23490 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
234a0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
234b0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
234c0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
234d0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
234e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
234f0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
23500 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
23510 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
23520 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
23530 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23540 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
23550 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23560 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
23570 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23580 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
23590 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
235a0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
235b0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
235c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
235d0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
235e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
235f0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
23600 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
23610 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
23620 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
23630 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
23640 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
23650 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23660 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
23670 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23680 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
23690 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
236a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
236b0 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
236c0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
236d0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
236e0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
236f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
23700 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
23710 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
23720 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
23730 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
23740 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
23750 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
23760 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
23770 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23780 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
23790 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
237a0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
237b0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
237c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
237d0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
237e0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
237f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
23800 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
23810 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
23820 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
23830 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
23840 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23850 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
23860 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
23870 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
23880 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23890 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
238a0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
238b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
238c0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
238d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
238e0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
238f0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
23900 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
23910 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
23920 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
23930 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23940 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
23950 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
23960 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23970 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
23980 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23990 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
239a0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
239b0 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
239c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
239d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
239e0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
239f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
23a00 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
23a10 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
23a20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
23a30 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
23a40 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
23a50 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
23a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23a70 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
23a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23a90 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
23aa0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
23ab0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
23ac0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
23ad0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
23ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23af0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
23b00 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
23b10 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
23b20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
23b30 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
23b40 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
23b50 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
23b60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
23b70 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
23b80 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
23b90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
23ba0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
23bb0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
23bc0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
23bd0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
23be0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
23bf0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
23c00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23c10 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
23c20 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23c30 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
23c40 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
23c50 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23c60 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
23c70 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
23c80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
23c90 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
23ca0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
23cb0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
23cc0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
23cd0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
23ce0 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
23cf0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
23d00 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
23d10 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
23d20 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
23d30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
23d40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
23d50 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
23d60 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
23d70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
23d80 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
23d90 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
23da0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
23db0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
23dc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
23dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
23de0 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
23df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23e00 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
23e10 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
23e20 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
23e30 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
23e40 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
23e50 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
23e60 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
23e70 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
23e80 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
23e90 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
23ea0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
23eb0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
23ec0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
23ed0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
23ee0 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
23ef0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23f00 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
23f10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
23f20 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
23f30 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
23f40 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
23f50 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
23f60 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
23f70 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
23f80 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
23f90 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
23fa0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
23fb0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
23fc0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
23fd0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
23fe0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
23ff0 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
24000 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
24010 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
24020 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
24030 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
24040 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
24050 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
24060 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
24070 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
24080 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
24090 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
240a0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
240b0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
240c0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
240d0 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
240e0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
240f0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
24100 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
24110 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
24120 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
24130 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
24140 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
24150 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
24160 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
24170 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
24180 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
24190 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
241a0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
241b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
241c0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
241d0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
241e0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
241f0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
24200 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
24210 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
24220 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
24230 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
24240 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
24250 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
24260 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
24270 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
24280 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
24290 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
242a0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
242b0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
242c0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
242d0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
242e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
242f0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
24300 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
24310 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
24320 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
24330 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
24340 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
24350 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
24360 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
24370 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
24380 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
24390 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
243a0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
243b0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
243c0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
243d0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
243e0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
243f0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
24400 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
24410 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
24420 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24430 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
24440 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
24450 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
24460 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
24470 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
24480 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
24490 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
244a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
244b0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
244c0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
244d0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
244e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
244f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24500 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
24510 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
24520 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
24530 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
24540 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
24550 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
24560 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
24570 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
24580 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
24590 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
245a0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
245b0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
245c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
245d0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
245e0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
245f0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
24600 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
24610 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
24620 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
24630 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
24640 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
24650 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
24660 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
24670 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
24680 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
24690 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
246a0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
246b0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
246c0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
246d0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
246e0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
246f0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
24700 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
24710 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
24720 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
24730 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
24740 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
24750 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
24760 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
24770 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
24780 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
24790 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
247a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
247b0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
247c0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
247d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
247e0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
247f0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
24800 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
24810 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
24820 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
24830 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
24840 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
24850 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
24860 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
24870 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
24880 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
24890 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
248a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
248b0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
248c0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
248d0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
248e0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
248f0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
24900 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
24910 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
24920 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
24930 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
24940 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
24950 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
24960 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
24970 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
24980 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
24990 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
249a0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
249b0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
249c0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
249d0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
249e0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
249f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
24a00 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
24a10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
24a20 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
24a30 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
24a40 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
24a50 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
24a60 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
24a70 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
24a80 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
24a90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
24aa0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
24ab0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
24ac0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
24ad0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
24ae0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
24af0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
24b00 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
24b10 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
24b20 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
24b30 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
24b40 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
24b50 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
24b60 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
24b70 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
24b80 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
24b90 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
24ba0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
24bb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
24bc0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
24bd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
24be0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
24bf0 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
24c00 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
24c10 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
24c20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
24c30 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
24c40 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
24c50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
24c60 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
24c70 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
24c80 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24c90 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
24ca0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24cb0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24cc0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24cd0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24ce0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24cf0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24d00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
24d10 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24d20 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24d30 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24d40 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
24d50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24d60 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
24d70 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
24d80 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
24d90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
24da0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
24db0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
24dc0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
24dd0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
24de0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
24df0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
24e00 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
24e10 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
24e20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
24e30 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
24e40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
24e50 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
24e60 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
24e70 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
24e80 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
24e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
24ea0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
24eb0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
24ec0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
24ed0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24ee0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
24ef0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
24f00 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
24f10 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
24f20 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
24f30 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
24f40 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
24f50 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
24f60 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
24f70 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
24f80 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
24f90 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
24fa0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
24fb0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
24fc0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
24fd0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
24fe0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
24ff0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
25000 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
25010 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
25020 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
25030 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
25040 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
25050 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
25060 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25070 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
25080 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
25090 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
250a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
250b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
250c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
250d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
250e0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
250f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
25100 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
25110 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
25120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25130 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
25140 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
25150 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
25160 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
25170 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
25180 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
25190 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
251a0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
251b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
251c0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
251d0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
251e0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
251f0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
25200 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
25210 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25220 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
25230 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25240 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
25250 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25260 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
25270 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
25280 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
25290 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
252a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
252b0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
252c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
252d0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
252e0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
252f0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
25300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
25310 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
25320 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
25330 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
25340 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
25350 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
25360 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
25370 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25380 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
25390 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
253a0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
253b0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
253c0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
253d0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
253e0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
253f0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
25400 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
25410 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
25420 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
25430 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
25440 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
25450 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
25460 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
25470 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
25480 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
25490 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
254a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
254b0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
254c0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
254d0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
254e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
254f0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
25500 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
25510 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
25520 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
25530 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
25540 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
25550 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
25560 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
25570 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
25580 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
25590 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
255a0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
255b0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
255c0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
255d0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
255e0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
255f0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
25600 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
25610 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
25620 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
25630 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
25640 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
25650 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
25660 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
25670 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
25680 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
25690 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
256a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
256b0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
256c0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
256d0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
256e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
256f0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
25700 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
25710 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
25720 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
25730 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
25740 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
25750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
25760 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
25770 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
25780 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
25790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
257a0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
257b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
257c0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
257d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
257e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
257f0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
25800 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
25810 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
25820 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25830 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
25840 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25850 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
25860 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
25870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25880 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
25890 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
258a0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
258b0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
258c0 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
258d0 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
258e0 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
258f0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
25900 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25910 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
25920 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
25930 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25940 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
25950 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
25960 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
25970 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
25980 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
25990 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
259a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
259b0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
259c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
259d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
259e0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
259f0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
25a00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
25a10 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
25a20 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
25a30 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
25a40 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
25a50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25a60 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
25a70 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
25a80 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
25a90 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
25aa0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
25ab0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
25ac0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
25ad0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
25ae0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
25af0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
25b00 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
25b10 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
25b20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
25b30 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
25b40 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
25b50 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
25b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
25b70 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
25b80 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
25b90 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
25ba0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25bb0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
25bc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
25bd0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
25be0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
25bf0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
25c00 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
25c10 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
25c20 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
25c30 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
25c40 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
25c50 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
25c60 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
25c70 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
25c80 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
25c90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
25ca0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
25cb0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
25cc0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
25cd0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
25ce0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
25cf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25d00 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
25d10 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
25d20 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
25d30 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
25d40 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
25d50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25d60 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
25d70 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
25d80 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
25d90 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
25da0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25db0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
25dc0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
25dd0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
25de0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
25df0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
25e00 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
25e10 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
25e20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25e30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
25e40 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
25e50 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
25e60 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
25e70 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
25e80 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
25e90 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
25ea0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
25eb0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
25ec0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
25ed0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
25ee0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
25ef0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
25f00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
25f10 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
25f20 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
25f30 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
25f40 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
25f50 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
25f60 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
25f70 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
25f80 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
25f90 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
25fa0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
25fb0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
25fc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
25fd0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
25fe0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
25ff0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
26000 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
26010 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
26020 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
26030 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
26040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
26050 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
26060 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
26070 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
26080 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
26090 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
260a0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
260b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
260c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
260d0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
260e0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
260f0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
26100 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
26110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26120 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
26130 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
26140 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
26150 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
26160 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
26170 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
26180 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
26190 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
261a0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
261b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
261c0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
261d0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
261e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
261f0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
26200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
26210 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
26220 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
26230 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
26240 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26250 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
26260 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
26270 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
26280 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26290 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
262a0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
262b0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
262c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
262d0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
262e0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
262f0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
26300 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26310 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
26320 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
26330 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
26340 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
26350 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
26360 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
26370 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
26380 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
26390 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
263a0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
263b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
263c0 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
263d0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
263e0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
263f0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
26400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
26410 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26420 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
26430 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
26440 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26450 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
26460 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
26470 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
26480 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
26490 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
264a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
264b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
264c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
264d0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
264e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
264f0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
26500 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
26510 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
26520 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
26530 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
26540 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
26550 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
26560 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
26570 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
26580 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
26590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
265a0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
265b0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
265c0 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
265d0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
265e0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
265f0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
26600 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
26610 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
26620 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
26630 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
26640 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
26650 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
26660 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
26670 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
26680 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
26690 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
266a0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
266b0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
266c0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
266d0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
266e0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
266f0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
26700 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
26710 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
26720 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
26730 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
26740 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
26750 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
26760 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
26770 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
26780 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
26790 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
267a0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
267b0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
267c0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
267d0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
267e0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
267f0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
26800 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
26810 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
26820 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
26830 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
26840 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
26850 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
26860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
26870 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
26880 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
26890 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
268a0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
268b0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
268c0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
268d0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
268e0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
268f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
26900 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
26910 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
26920 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
26930 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
26940 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
26950 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
26960 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
26970 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
26980 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
26990 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
269a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
269b0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
269c0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
269d0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
269e0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
269f0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
26a00 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
26a10 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
26a20 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
26a30 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
26a40 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
26a50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
26a60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
26a70 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
26a80 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
26a90 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
26aa0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
26ab0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
26ac0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
26ad0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
26ae0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
26af0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
26b00 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
26b10 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26b20 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
26b30 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
26b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
26b50 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
26b60 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
26b70 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
26b80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
26b90 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
26ba0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
26bb0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
26bc0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
26bd0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26be0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
26bf0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
26c00 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
26c10 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
26c20 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
26c30 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
26c40 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
26c50 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
26c60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
26c70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
26c80 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
26c90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
26ca0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
26cb0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
26cc0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
26cd0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
26ce0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
26cf0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
26d00 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
26d10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
26d20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26d30 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
26d40 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
26d50 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
26d60 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
26d70 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
26d80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26d90 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
26da0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
26db0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
26dc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
26dd0 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61  ) then that para
26de0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
26df0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
26e00 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
26e10 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
26e20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
26e30 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
26e40 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
26e50 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
26e60 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
26e70 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
26e80 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
26e90 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
26ea0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
26eb0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
26ec0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
26ed0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
26ee0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
26ef0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
26f00 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
26f10 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
26f20 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
26f30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
26f40 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
26f50 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
26f60 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
26f70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26f80 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
26f90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26fa0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
26fb0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
26fc0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
26fd0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
26fe0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
26ff0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
27000 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
27010 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
27020 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
27030 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
27040 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
27050 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
27060 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  lob(),.** sqlite
27070 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f  3_bind_text(), o
27080 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
27090 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20  ext16() fails.  
270a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
270b0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
270c0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
270d0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
270e0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
270f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
27100 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
27110 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
27120 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
27130 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
27140 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
27150 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
27160 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
27170 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
27180 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
27190 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
271a0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
271b0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
271c0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
271d0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
271e0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
271f0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
27200 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
27210 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
27220 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
27230 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
27240 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
27250 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
27260 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
27270 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
27280 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
27290 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
272a0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
272b0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
272c0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
272d0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
272e0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
272f0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
27300 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
27310 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
27320 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
27330 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
27340 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
27350 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
27360 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
27370 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
27380 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
27390 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
273a0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
273b0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
273c0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
273d0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
273e0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
273f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
27400 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
27410 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
27420 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
27430 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
27440 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
27450 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
27460 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
27470 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
27480 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
27490 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
274a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
274b0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
274c0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
274d0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
274e0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
274f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27500 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
27510 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
27520 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
27530 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
27540 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
27550 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
27560 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
27570 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27580 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
27590 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
275a0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
275b0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
275c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
275d0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
275e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
275f0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
27600 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
27610 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
27620 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
27630 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
27640 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
27650 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
27660 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
27670 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
27680 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
27690 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
276a0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
276b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
276c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
276d0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
276e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
276f0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
27700 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27710 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
27720 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27730 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
27740 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
27750 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
27760 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
27770 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
27780 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
27790 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
277a0 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
277b0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
277c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
277d0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
277e0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
277f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27800 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
27810 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27820 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
27830 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
27840 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27850 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
27860 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
27870 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
27880 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
27890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
278a0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
278b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
278c0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
278d0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
278e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
278f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27900 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
27910 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27920 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
27930 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
27940 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
27950 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27960 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
27970 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
27980 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
27990 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
279a0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
279b0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
279c0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
279d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
279e0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
279f0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
27a00 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
27a10 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
27a20 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
27a30 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
27a40 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
27a50 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
27a60 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
27a70 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
27a80 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
27a90 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
27aa0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
27ab0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
27ac0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
27ad0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
27ae0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
27af0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
27b00 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
27b10 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
27b20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
27b30 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
27b40 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
27b50 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
27b60 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
27b70 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
27b80 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
27b90 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
27ba0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
27bb0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
27bc0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
27bd0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
27be0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27bf0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
27c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
27c10 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27c20 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
27c30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27c40 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
27c50 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27c60 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
27c70 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
27c80 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
27c90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27ca0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
27cb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27cc0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
27cd0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
27ce0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
27cf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27d00 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
27d10 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
27d20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
27d30 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
27d40 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
27d50 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
27d60 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
27d70 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
27d80 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
27d90 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
27da0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
27db0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
27dc0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
27dd0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
27de0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
27df0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
27e00 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
27e10 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
27e20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
27e30 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
27e40 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
27e50 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
27e60 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
27e70 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
27e80 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
27e90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
27ea0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
27eb0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
27ec0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
27ed0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
27ee0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
27ef0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
27f00 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
27f10 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
27f20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
27f30 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
27f40 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
27f50 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
27f60 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
27f70 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
27f80 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
27f90 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
27fa0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
27fb0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
27fc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
27fd0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
27fe0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
27ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
28000 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
28010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28020 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
28030 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
28040 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28050 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
28060 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
28070 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28080 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
28090 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
280a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
280b0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
280c0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
280d0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
280e0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
280f0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
28100 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
28110 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
28120 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
28130 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
28140 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
28150 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
28160 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
28170 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
28180 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
28190 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
281a0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
281b0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
281c0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
281d0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
281e0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
281f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
28200 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
28210 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
28220 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
28230 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28240 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
28250 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28260 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28270 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28280 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28290 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
282a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
282b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
282c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
282d0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
282e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
282f0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
28300 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
28310 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
28320 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
28330 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
28340 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
28350 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
28360 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
28370 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
28380 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28390 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
283a0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
283b0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
283c0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
283d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
283e0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
283f0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
28400 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
28410 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
28420 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
28430 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
28440 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
28450 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
28460 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
28470 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
28480 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
28490 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
284a0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
284b0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
284c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
284d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
284e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
284f0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
28500 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
28510 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
28520 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
28530 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
28540 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
28550 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
28560 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
28570 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28580 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
28590 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
285a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
285b0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
285c0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
285d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
285e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
285f0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
28600 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
28610 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
28620 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
28630 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
28640 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
28650 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
28660 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
28670 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28680 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28690 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
286a0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
286b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
286c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
286d0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
286e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
286f0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
28700 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28710 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
28720 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
28730 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
28740 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
28750 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
28760 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
28770 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
28780 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
28790 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
287a0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
287b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
287c0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
287d0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
287e0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
287f0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
28800 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
28810 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28820 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
28830 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
28840 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
28850 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
28860 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
28870 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
28880 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
28890 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
288a0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
288b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
288c0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
288d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
288e0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
288f0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
28900 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
28910 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
28920 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
28930 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
28940 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
28950 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
28960 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
28970 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
28980 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
28990 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
289a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
289b0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
289c0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
289d0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
289e0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
289f0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
28a00 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
28a10 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
28a20 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
28a30 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
28a40 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
28a50 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
28a60 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
28a70 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
28a80 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
28a90 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
28aa0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28ab0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28ac0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
28ad0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28ae0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
28af0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28b00 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
28b10 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
28b20 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
28b30 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
28b40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
28b50 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
28b60 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
28b70 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
28b80 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
28b90 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
28ba0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
28bb0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
28bc0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
28bd0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
28be0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
28bf0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
28c00 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
28c10 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
28c20 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
28c30 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
28c40 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
28c50 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
28c60 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
28c70 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
28c80 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
28c90 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
28ca0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
28cb0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
28cc0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
28cd0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
28ce0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
28cf0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
28d00 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
28d10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
28d20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
28d30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28d40 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
28d50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
28d60 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
28d70 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
28d80 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
28d90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
28da0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
28db0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
28dc0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
28dd0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
28de0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
28df0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
28e00 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
28e10 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
28e20 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
28e30 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
28e40 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
28e50 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
28e60 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
28e70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
28e80 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
28e90 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
28ea0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28eb0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
28ec0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
28ed0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
28ee0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
28ef0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
28f00 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
28f10 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
28f20 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
28f30 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
28f40 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
28f50 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
28f60 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
28f70 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
28f80 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
28f90 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
28fa0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
28fb0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
28fc0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
28fd0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
28fe0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
28ff0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
29000 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
29010 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
29020 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
29030 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
29040 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
29050 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
29060 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
29070 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
29080 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
29090 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
290a0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
290b0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
290c0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
290d0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
290e0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
290f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
29100 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
29110 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
29120 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
29130 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
29140 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
29150 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
29160 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
29170 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
29180 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
29190 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
291a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
291b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
291c0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
291d0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
291e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
291f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
29200 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
29210 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
29220 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
29230 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
29240 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
29250 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
29260 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
29270 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
29280 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
29290 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
292a0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
292b0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
292c0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
292d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
292e0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
292f0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
29300 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
29310 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29320 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
29330 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
29340 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
29350 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
29360 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
29370 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
29390 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
293a0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
293b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
293c0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
293d0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
293e0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
293f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29400 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
29410 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29420 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
29430 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29440 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
29450 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
29460 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
29470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
29480 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
29490 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
294a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
294b0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
294c0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
294d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
294e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
294f0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
29500 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
29510 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
29520 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
29530 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29540 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
29550 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
29560 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
29570 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
29580 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
29590 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
295a0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
295b0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
295c0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
295d0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
295e0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
295f0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
29600 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
29610 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
29620 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
29630 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
29640 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
29650 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
29660 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
29670 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
29680 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
29690 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
296a0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
296b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
296c0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
296d0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
296e0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
296f0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
29700 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
29710 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
29720 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
29730 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
29740 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
29750 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
29760 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
29770 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
29780 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
29790 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
297a0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
297b0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
297c0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
297d0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
297e0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
297f0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
29800 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
29810 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
29820 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
29830 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
29840 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
29850 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
29860 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
29870 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
29880 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
29890 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
298a0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
298b0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
298c0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
298d0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
298e0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
298f0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
29900 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
29910 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
29920 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
29930 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
29940 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
29950 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
29960 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
29970 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
29980 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
29990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
299a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
299b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
299c0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
299d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
299e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
299f0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
29a00 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
29a10 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
29a20 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
29a30 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
29a40 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
29a50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29a60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
29a70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
29a80 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
29a90 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
29aa0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
29ab0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
29ac0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
29ad0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
29ae0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
29af0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
29b00 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
29b10 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
29b20 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
29b30 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
29b40 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
29b50 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
29b60 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
29b70 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
29b80 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
29b90 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
29ba0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
29bb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29bc0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
29bd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29be0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
29bf0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
29c00 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
29c10 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
29c20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29c30 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
29c40 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
29c50 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
29c60 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
29c70 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
29c80 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
29c90 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
29ca0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
29cb0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
29cc0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
29cd0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
29ce0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
29cf0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
29d00 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
29d10 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
29d20 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
29d30 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
29d40 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
29d50 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
29d60 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
29d70 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
29d80 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
29d90 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
29da0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
29db0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
29dc0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
29dd0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
29de0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
29df0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
29e00 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
29e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
29e20 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
29e30 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
29e40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29e50 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
29e60 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
29e70 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
29e80 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
29e90 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
29ea0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
29eb0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
29ec0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
29ed0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
29ee0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
29ef0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
29f00 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
29f10 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
29f20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
29f30 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
29f40 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
29f50 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
29f60 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
29f70 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
29f80 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
29f90 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
29fa0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
29fb0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
29fc0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
29fd0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
29fe0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
29ff0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2a000 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2a010 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2a020 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2a030 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2a040 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2a050 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2a060 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2a070 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2a080 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2a090 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2a0a0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2a0b0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2a0c0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2a0d0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2a0e0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2a0f0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2a100 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2a110 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a120 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2a130 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2a140 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2a150 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2a160 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2a170 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2a180 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2a190 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2a1a0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2a1b0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2a1c0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2a1d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2a1e0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2a1f0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2a200 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2a210 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2a220 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2a230 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2a240 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2a250 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2a260 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2a270 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2a280 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2a290 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2a2a0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2a2b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2a2c0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2a2d0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2a2e0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2a2f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a300 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2a310 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a320 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2a330 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2a340 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2a350 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2a360 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2a370 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2a380 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2a390 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2a3a0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2a3b0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2a3c0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2a3d0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2a3e0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2a3f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a400 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2a410 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2a420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2a430 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2a440 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2a450 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2a460 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2a470 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2a480 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2a490 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2a4a0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2a4b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a4c0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2a4d0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2a4e0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2a4f0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2a500 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2a510 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2a520 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2a530 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2a540 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2a550 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2a560 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2a570 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2a580 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2a590 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2a5a0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2a5b0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2a5c0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2a5d0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2a5e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2a5f0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2a600 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2a610 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2a620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a630 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2a640 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2a650 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2a660 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2a670 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2a680 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2a690 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2a6a0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2a6b0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2a6c0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2a6d0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2a6e0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2a6f0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2a700 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a710 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2a720 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2a730 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2a740 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2a750 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2a760 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2a770 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2a780 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2a790 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2a7a0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2a7b0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2a7c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2a7d0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2a7e0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2a7f0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2a800 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2a810 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2a820 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2a830 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2a840 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2a850 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2a860 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2a870 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2a880 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2a890 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2a8a0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2a8b0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2a8c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a8d0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2a8e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2a8f0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2a900 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2a910 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2a920 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2a930 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2a940 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2a950 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2a960 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2a970 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2a980 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2a990 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2a9a0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2a9b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a9c0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2a9d0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2a9e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2a9f0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2aa00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aa10 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2aa20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2aa30 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2aa40 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2aa50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2aa60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2aa70 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2aa80 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2aa90 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2aaa0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2aab0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2aac0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2aad0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2aae0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2aaf0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2ab00 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
2ab10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2ab20 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2ab30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2ab40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2ab50 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2ab60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ab70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2ab80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ab90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2aba0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2abb0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2abc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2abd0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2abe0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2abf0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2ac00 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2ac10 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2ac20 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2ac30 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2ac40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2ac50 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2ac60 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2ac70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2ac80 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2ac90 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2aca0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2acb0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2acc0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2acd0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2ace0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2acf0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ad00 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ad10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ad20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2ad30 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2ad40 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2ad50 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2ad60 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2ad70 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2ad80 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2ad90 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2ada0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2adb0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2adc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2add0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2ade0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2adf0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2ae00 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2ae10 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2ae20 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2ae30 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2ae40 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2ae50 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2ae60 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2ae70 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2ae80 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ae90 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2aea0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2aeb0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2aec0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2aed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aee0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2aef0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2af00 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2af10 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2af20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2af30 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2af40 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2af50 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2af60 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2af70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2af80 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2af90 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2afa0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2afb0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2afc0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2afd0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2afe0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2aff0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2b000 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2b010 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2b020 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2b030 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2b040 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2b050 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2b060 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2b070 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2b080 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2b090 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2b0a0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2b0b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2b0c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2b0d0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2b0e0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2b0f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2b100 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2b110 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2b120 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2b130 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2b140 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2b150 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2b160 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2b170 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2b180 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2b190 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2b1a0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2b1b0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2b1c0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2b1d0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2b1e0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2b1f0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2b200 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2b210 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2b220 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2b230 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2b240 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2b250 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2b260 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2b270 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2b280 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2b290 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2b2a0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2b2b0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2b2c0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2b2d0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2b2e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2b2f0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2b300 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b310 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2b320 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2b330 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2b340 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2b350 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2b360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b370 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2b380 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2b390 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2b3a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2b3b0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2b3c0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2b3d0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2b3e0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2b3f0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2b400 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2b410 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2b420 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2b430 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b440 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2b450 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2b460 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2b470 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2b480 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2b490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2b4a0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2b4b0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2b4c0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2b4d0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2b4e0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2b4f0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2b500 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2b510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2b520 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2b530 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2b540 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2b550 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b560 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2b570 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2b580 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2b590 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2b5a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b5b0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2b5c0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2b5d0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2b5e0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2b5f0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2b600 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2b610 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2b620 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2b630 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2b640 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2b650 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2b660 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2b670 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2b680 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2b690 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2b6a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2b6b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b6c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2b6d0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2b6e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2b6f0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2b700 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2b710 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2b720 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2b730 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2b740 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2b750 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b760 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2b770 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2b780 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2b790 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2b7a0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2b7b0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2b7c0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2b7d0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2b7e0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2b7f0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b800 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2b810 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2b820 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2b830 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2b840 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2b850 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2b860 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2b870 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2b880 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2b890 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2b8a0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2b8b0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2b8c0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2b8d0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2b8e0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2b8f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2b900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2b910 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2b920 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2b930 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2b940 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2b950 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2b960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2b970 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2b980 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2b990 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b9a0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2b9b0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2b9c0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2b9d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b9e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2b9f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2ba00 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2ba10 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2ba20 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2ba30 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2ba40 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2ba50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ba60 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2ba70 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2ba80 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2ba90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2baa0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2bab0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2bac0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2bad0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2bae0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2baf0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2bb00 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2bb10 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2bb20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2bb30 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2bb40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2bb50 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2bb60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2bb70 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2bb80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bb90 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2bba0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2bbb0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2bbc0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2bbd0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2bbe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bbf0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2bc00 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2bc10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2bc20 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2bc30 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2bc40 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2bc50 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2bc60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bc70 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2bc80 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2bc90 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2bca0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2bcb0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2bcc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2bcd0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2bce0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2bcf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2bd00 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2bd10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2bd20 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2bd30 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2bd40 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2bd50 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2bd60 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2bd70 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2bd80 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2bd90 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2bda0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2bdb0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2bdc0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2bdd0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2bde0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2bdf0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2be00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2be10 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2be20 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2be30 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2be40 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2be50 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2be60 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2be70 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2be80 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2be90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2bea0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2beb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2bec0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2bed0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2bee0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2bef0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2bf00 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2bf10 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2bf20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2bf30 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2bf40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bf50 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2bf60 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2bf70 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2bf80 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2bf90 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2bfa0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2bfb0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2bfc0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2bfd0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2bfe0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2bff0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2c000 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2c010 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2c020 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2c030 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c040 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2c050 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c060 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2c070 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2c080 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2c090 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2c0a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2c0b0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2c0c0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2c0d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c0e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2c0f0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2c100 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2c110 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2c120 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2c130 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2c140 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2c150 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2c160 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2c170 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2c180 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2c190 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2c1a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2c1b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c1c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2c1d0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2c1e0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2c1f0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2c200 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2c210 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2c220 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2c230 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2c240 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2c250 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2c260 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2c270 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2c280 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2c290 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2c2a0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2c2b0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2c2c0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2c2d0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2c2e0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2c2f0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2c300 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2c310 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2c320 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2c330 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2c340 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2c350 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2c360 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2c370 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2c380 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2c390 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2c3a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2c3b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2c3c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2c3d0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2c3e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2c3f0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2c400 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2c410 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2c420 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2c430 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2c440 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2c450 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2c460 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2c470 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2c480 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2c490 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2c4a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2c4b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2c4c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2c4d0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2c4e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2c4f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2c500 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2c510 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2c520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2c530 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2c540 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2c550 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
2c560 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2c570 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2c580 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2c590 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2c5a0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2c5b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2c5c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2c5d0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
2c5e0 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
2c5f0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2c600 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2c610 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
2c620 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2c630 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2c640 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
2c650 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2c660 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2c670 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2c680 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2c690 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2c6a0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2c6b0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2c6c0 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
2c6d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2c6e0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2c6f0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2c700 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2c710 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2c720 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2c730 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2c740 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2c750 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2c760 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2c770 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2c780 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2c790 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2c7a0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2c7b0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2c7c0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2c7d0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2c7e0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2c7f0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2c800 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2c810 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2c820 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2c830 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2c840 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2c850 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2c860 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2c870 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2c880 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2c890 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2c8a0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2c8b0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2c8c0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2c8d0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2c8e0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2c8f0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2c900 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c910 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2c920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c930 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2c940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c950 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2c960 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2c970 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2c980 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2c990 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2c9a0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2c9b0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2c9c0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2c9d0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2c9e0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2c9f0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2ca00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2ca10 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2ca20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2ca30 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2ca40 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2ca50 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2ca60 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2ca70 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2ca80 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2ca90 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2caa0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2cab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2cac0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2cad0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2cae0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2caf0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2cb00 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2cb10 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2cb20 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2cb30 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2cb40 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2cb50 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2cb60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cb70 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2cb80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cb90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2cba0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2cbb0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2cbc0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2cbd0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2cbe0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2cbf0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2cc00 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2cc10 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2cc20 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2cc30 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2cc40 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2cc50 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2cc60 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2cc70 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2cc80 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2cc90 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2cca0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2ccb0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2ccc0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2ccd0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2cce0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2ccf0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2cd00 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2cd10 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2cd20 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2cd30 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2cd40 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2cd50 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2cd60 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2cd70 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2cd80 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2cd90 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2cda0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2cdb0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2cdc0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2cdd0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2cde0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2cdf0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2ce00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ce10 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2ce20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2ce30 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2ce40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ce50 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2ce60 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2ce70 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2ce80 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2ce90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2cea0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2ceb0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2cec0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2ced0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2cee0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2cef0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cf00 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2cf10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2cf20 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2cf30 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2cf40 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2cf50 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2cf60 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2cf70 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2cf80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf90 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2cfa0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2cfb0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2cfc0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2cfd0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2cfe0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2cff0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d000 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2d010 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2d020 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2d030 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2d040 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2d050 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2d060 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2d070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d080 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2d090 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2d0a0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2d0b0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2d0c0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2d0d0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2d0e0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2d0f0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2d100 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d110 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2d120 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2d130 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2d140 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2d150 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2d160 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2d170 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2d180 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2d190 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2d1a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2d1b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d1c0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2d1d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d1e0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
2d1f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2d200 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
2d210 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2d220 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2d230 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2d240 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2d250 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2d260 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2d270 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2d280 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2d290 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2d2a0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2d2b0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2d2c0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2d2d0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2d2e0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2d2f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2d300 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2d310 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2d320 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
2d330 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d340 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
2d350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d360 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2d370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d380 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2d390 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2d3a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d3b0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2d3c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d3d0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2d3e0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2d3f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d400 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2d410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2d420 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d430 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2d440 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2d450 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2d460 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d470 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
2d480 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2d490 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2d4a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d4b0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
2d4c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2d4d0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2d4e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d4f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2d500 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
2d510 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d520 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
2d530 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2d540 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2d550 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d560 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2d570 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2d580 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d590 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2d5a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2d5b0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2d5c0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2d5d0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2d5e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2d5f0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2d600 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2d610 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2d620 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
2d630 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
2d640 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2d650 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
2d660 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
2d670 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
2d680 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
2d690 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
2d6a0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2d6b0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
2d6c0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
2d6d0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
2d6e0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
2d6f0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
2d700 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
2d710 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
2d720 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2d730 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2d740 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
2d750 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
2d760 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
2d770 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
2d780 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
2d790 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
2d7a0 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
2d7b0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
2d7c0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
2d7d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2d7e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2d7f0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
2d800 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
2d810 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d820 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
2d830 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2d840 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2d850 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2d860 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
2d870 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
2d880 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
2d890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2d8a0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2d8b0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
2d8c0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
2d8d0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
2d8e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d8f0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
2d900 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
2d910 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
2d920 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
2d930 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2d940 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
2d950 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
2d960 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2d970 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2d980 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
2d990 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
2d9a0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2d9b0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2d9c0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
2d9d0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
2d9e0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
2d9f0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
2da00 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
2da10 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
2da20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2da30 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
2da40 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2da50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2da60 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
2da70 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2da80 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
2da90 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2daa0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2dab0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2dac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2dad0 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2dae0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2daf0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2db00 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2db10 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
2db20 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
2db30 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
2db40 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
2db50 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2db60 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2db70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
2db80 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
2db90 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
2dba0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2dbb0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
2dbc0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
2dbd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2dbe0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2dbf0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2dc00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2dc10 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
2dc20 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2dc30 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2dc40 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
2dc50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2dc60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2dc70 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2dc80 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2dc90 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2dca0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2dcb0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2dcc0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
2dcd0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2dce0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
2dcf0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
2dd00 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
2dd10 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2dd20 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
2dd30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2dd40 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2dd50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2dd60 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2dd70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dd80 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
2dd90 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
2dda0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2ddb0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
2ddc0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2ddd0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2dde0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2ddf0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2de00 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
2de10 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
2de20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
2de30 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
2de40 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
2de50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2de60 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
2de70 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
2de80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2de90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2dea0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
2deb0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
2dec0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2ded0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2dee0 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2def0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2df00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2df10 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2df20 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2df30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2df40 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2df50 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2df60 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
2df70 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
2df80 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2df90 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
2dfa0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
2dfb0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2dfc0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
2dfd0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
2dfe0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
2dff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2e000 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
2e010 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
2e020 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
2e030 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e040 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
2e050 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
2e060 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
2e070 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
2e080 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
2e090 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
2e0a0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
2e0b0 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
2e0c0 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
2e0d0 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
2e0e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e0f0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
2e100 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2e110 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2e120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e130 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2e140 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2e150 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2e160 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
2e170 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
2e180 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2e190 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2e1a0 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
2e1b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e1c0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
2e1d0 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
2e1e0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
2e1f0 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
2e200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2e210 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2e220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2e230 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2e240 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
2e250 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
2e260 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2e270 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
2e280 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
2e290 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
2e2a0 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
2e2b0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2e2c0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
2e2d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2e2e0 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
2e2f0 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
2e300 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
2e310 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
2e320 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
2e330 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
2e340 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
2e350 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
2e360 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
2e370 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
2e380 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
2e390 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
2e3a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
2e3b0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
2e3c0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2e3d0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
2e3e0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e3f0 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
2e400 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
2e410 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
2e420 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2e430 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2e440 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
2e450 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2e460 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
2e470 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
2e480 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2e490 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2e4a0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
2e4b0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
2e4c0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
2e4d0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
2e4e0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
2e4f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2e500 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
2e510 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
2e520 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
2e530 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
2e540 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
2e550 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
2e560 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
2e570 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
2e580 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
2e590 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72  arameters.  Ever
2e5a0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
2e5b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2e5c0 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  st be able to wo
2e5d0 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38  rk.** with UTF-8
2e5e0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
2e5f0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
2e600 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
2e610 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
2e620 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
2e630 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
2e640 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
2e650 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
2e660 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
2e670 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e680 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
2e690 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2e6a0 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
2e6b0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2e6c0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
2e6d0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
2e6e0 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
2e6f0 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
2e700 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2e710 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2e720 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
2e730 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
2e740 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
2e750 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
2e760 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
2e770 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
2e780 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
2e790 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
2e7a0 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
2e7b0 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
2e7c0 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
2e7d0 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
2e7e0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
2e7f0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2e800 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
2e810 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
2e820 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
2e830 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
2e840 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
2e850 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2e860 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
2e870 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
2e880 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
2e890 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
2e8a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2e8b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2e8c0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
2e8d0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
2e8e0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2e8f0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2e900 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2e910 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2e920 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2e930 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2e940 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2e950 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
2e960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2e970 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2e980 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2e990 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
2e9a0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
2e9b0 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
2e9c0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
2e9d0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
2e9e0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
2e9f0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2ea00 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2ea10 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2ea20 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2ea30 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2ea40 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
2ea50 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
2ea60 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
2ea70 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2ea80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2ea90 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2eaa0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
2eab0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2eac0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
2ead0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
2eae0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
2eaf0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2eb00 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2eb10 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
2eb20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
2eb30 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
2eb40 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2eb50 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
2eb60 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
2eb70 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
2eb80 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2eb90 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
2eba0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
2ebb0 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
2ebc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ebd0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
2ebe0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2ebf0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
2ec00 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
2ec10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ec20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
2ec30 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
2ec40 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
2ec50 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
2ec60 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2ec70 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
2ec80 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
2ec90 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
2eca0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
2ecb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2ecc0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
2ecd0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
2ece0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2ecf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ed00 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
2ed10 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
2ed20 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
2ed30 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2ed40 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2ed50 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
2ed60 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
2ed70 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
2ed80 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
2ed90 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
2eda0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
2edb0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
2edc0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
2edd0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
2ede0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
2edf0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
2ee00 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
2ee10 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
2ee20 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
2ee30 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
2ee40 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
2ee50 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
2ee60 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
2ee70 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
2ee80 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
2ee90 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2eea0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2eeb0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
2eec0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
2eed0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2eee0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
2eef0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
2ef00 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
2ef10 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
2ef20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
2ef30 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2ef40 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2ef50 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
2ef60 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
2ef70 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2ef80 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2ef90 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
2efa0 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
2efb0 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
2efc0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2efd0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2efe0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2eff0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
2f000 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
2f010 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
2f020 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
2f030 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
2f040 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
2f050 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2f060 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
2f070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f080 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
2f090 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
2f0a0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
2f0b0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
2f0c0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
2f0d0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
2f0e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f0f0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
2f100 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
2f110 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
2f120 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
2f130 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
2f140 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
2f150 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2f160 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
2f170 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2f180 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2f190 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2f1a0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2f1b0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2f1c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2f1d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f1e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2f1f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2f200 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2f210 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2f220 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2f230 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2f240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f250 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2f260 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f270 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2f280 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
2f290 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2f2a0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2f2b0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2f2c0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2f2d0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2f2e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2f2f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2f300 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2f310 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f320 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2f330 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2f340 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2f350 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2f360 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2f370 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
2f380 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2f390 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2f3a0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2f3b0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2f3c0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2f3d0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2f3e0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2f3f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2f400 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2f410 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2f420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2f430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2f440 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2f450 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2f460 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
2f470 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2f480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f490 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2f4a0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2f4b0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
2f4c0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
2f4d0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
2f4e0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
2f4f0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
2f500 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
2f510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f520 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
2f530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f540 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
2f550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f560 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
2f570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f580 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
2f590 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
2f5a0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
2f5b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2f5c0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
2f5d0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2f5e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
2f5f0 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
2f600 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2f610 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
2f620 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2f630 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
2f640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f650 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
2f660 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
2f670 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2f680 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
2f690 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
2f6a0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
2f6b0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
2f6c0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
2f6d0 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
2f6e0 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
2f6f0 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
2f700 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
2f710 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
2f720 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
2f730 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
2f740 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2f750 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
2f760 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
2f770 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
2f780 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
2f790 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
2f7a0 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
2f7b0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
2f7c0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
2f7d0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
2f7e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2f7f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f800 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
2f810 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
2f820 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2f830 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
2f840 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2f850 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2f860 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
2f870 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
2f880 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f890 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2f8a0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2f8b0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
2f8c0 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
2f8d0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2f8e0 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
2f8f0 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
2f900 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
2f910 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2f920 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
2f930 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
2f940 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
2f950 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
2f960 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
2f970 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2f980 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
2f990 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
2f9a0 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
2f9b0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
2f9c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2f9d0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
2f9e0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
2f9f0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
2fa00 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
2fa10 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
2fa20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
2fa30 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
2fa40 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2fa50 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
2fa60 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
2fa70 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
2fa80 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
2fa90 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
2faa0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2fab0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2fac0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2fad0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2fae0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
2faf0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
2fb00 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2fb10 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2fb20 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
2fb30 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2fb40 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
2fb50 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
2fb60 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
2fb70 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2fb80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2fb90 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
2fba0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2fbb0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
2fbc0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
2fbd0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
2fbe0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
2fbf0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
2fc00 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
2fc10 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
2fc20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2fc30 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
2fc40 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
2fc50 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
2fc60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2fc70 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
2fc80 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
2fc90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2fca0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
2fcb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2fcc0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
2fcd0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
2fce0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2fcf0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2fd00 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
2fd10 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2fd20 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
2fd30 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
2fd40 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
2fd50 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
2fd60 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
2fd70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2fd80 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
2fd90 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
2fda0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
2fdb0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
2fdc0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
2fdd0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
2fde0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2fdf0 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
2fe00 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
2fe10 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
2fe20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
2fe30 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
2fe40 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
2fe50 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
2fe60 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
2fe70 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
2fe80 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
2fe90 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
2fea0 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
2feb0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
2fec0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
2fed0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
2fee0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
2fef0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2ff00 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
2ff10 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
2ff20 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
2ff30 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
2ff40 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
2ff50 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
2ff60 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
2ff70 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2ff80 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
2ff90 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
2ffa0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
2ffb0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
2ffc0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
2ffd0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
2ffe0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
2fff0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
30000 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
30010 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
30020 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
30030 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
30040 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
30050 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
30060 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
30070 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
30080 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
30090 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
300a0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
300b0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
300c0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
300d0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
300e0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
300f0 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
30100 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30110 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
30120 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30130 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
30140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30150 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
30160 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
30170 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
30180 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
30190 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
301a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
301b0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
301c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
301d0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
301e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
301f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
30200 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
30210 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30220 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
30230 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30240 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
30250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
30260 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
30270 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
30280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30290 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
302a0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
302b0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
302c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
302d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
302e0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
302f0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
30300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
30310 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
30320 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
30330 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
30340 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
30350 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
30360 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
30370 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
30380 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
30390 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
303a0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
303b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
303c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
303d0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
303e0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
303f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
30400 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
30410 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
30420 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30430 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30440 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30450 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
30460 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
30470 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
30480 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
30490 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
304a0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
304b0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
304c0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
304d0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
304e0 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
304f0 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
30500 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
30510 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
30520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
30530 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
30540 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
30550 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
30560 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
30570 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30580 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
30590 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
305a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
305b0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
305c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
305d0 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
305e0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
305f0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
30600 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
30610 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
30620 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
30630 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
30640 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
30650 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30660 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
30670 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
30680 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
30690 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
306a0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
306b0 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
306c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
306d0 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
306e0 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
306f0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
30700 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
30710 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
30720 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
30730 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
30740 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
30750 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
30760 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
30770 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
30780 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
30790 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
307a0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
307b0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
307c0 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
307d0 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
307e0 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
307f0 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
30800 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
30810 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30820 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
30830 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
30840 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
30850 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
30860 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
30870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30880 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
30890 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
308a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
308b0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
308c0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
308d0 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
308e0 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  y allocate error
308f0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
30900 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
30910 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
30920 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
30930 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
30940 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
30950 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
30960 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
30970 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
30980 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
30990 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
309a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
309b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
309c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
309d0 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
309e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
309f0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
30a00 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
30a10 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
30a20 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  tion.)^.**.** ^S
30a30 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
30a40 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
30a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
30a60 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
30a70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
30a80 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
30a90 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
30aa0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
30ab0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
30ac0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
30ad0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
30ae0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
30af0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
30b00 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
30b10 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
30b20 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
30b30 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
30b40 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
30b50 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
30b60 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
30b70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
30b80 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
30b90 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30ba0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
30bb0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
30bc0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
30bd0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
30be0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
30bf0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30c00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30c10 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
30c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30c30 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
30c40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
30c50 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
30c60 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
30c70 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
30c80 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
30c90 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
30ca0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
30cb0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
30cc0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
30cd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
30ce0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
30cf0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
30d00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30d10 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
30d20 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
30d30 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
30d40 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
30d50 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
30d60 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
30d70 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
30d80 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
30d90 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
30da0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30db0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30dc0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
30dd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
30de0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
30df0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
30e00 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
30e10 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
30e20 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
30e30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30e40 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
30e50 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
30e60 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
30e70 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
30e80 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
30e90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
30ea0 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
30eb0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
30ec0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30ed0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
30ee0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30ef0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
30f00 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
30f10 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
30f20 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
30f30 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
30f40 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
30f50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
30f60 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
30f70 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
30f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
30f90 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
30fa0 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Data.**.** The 
30fb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
30fc0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
30fd0 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
30fe0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
30ff0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
31000 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
31010 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
31020 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
31030 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
31040 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
31050 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
31060 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
31070 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
31080 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
31090 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
310a0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
310b0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
310c0 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
310d0 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
310e0 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
310f0 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
31100 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
31110 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
31120 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
31130 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
31140 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
31150 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
31160 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
31170 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
31180 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
31190 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
311a0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
311b0 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
311c0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
311d0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
311e0 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
311f0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
31200 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
31210 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
31220 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
31230 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
31240 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
31250 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
31260 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
31270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31280 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
31290 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
312a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
312b0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
312c0 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
312d0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
312e0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
312f0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
31300 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
31310 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
31320 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31330 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61  ion. ^If no meta
31340 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
31350 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
31360 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
31370 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
31380 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
31390 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
313a0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
313b0 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
313c0 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
313d0 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
313e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
313f0 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
31400 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31410 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31420 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
31430 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
31440 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
31450 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
31460 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
31470 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
31480 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
31490 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
314a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
314b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
314c0 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
314d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
314e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
314f0 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
31500 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
31510 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
31520 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69  troyed..** ^If i
31530 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
31540 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
31550 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
31560 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
31570 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
31580 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
315a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
315b0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
315c0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
315d0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
315e0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
315f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
31600 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
31610 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
31620 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
31630 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
31640 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
31650 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
31660 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
31670 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
31680 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
31690 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67  me.  ^The only g
316a0 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
316b0 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
316c0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
316d0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
316e0 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
316f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
31700 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
31710 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
31720 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
31730 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
31740 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
31750 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
31760 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
31770 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
31780 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
31790 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a  arameters].)^.**
317a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
317b0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
317c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
317d0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
317e0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
317f0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31800 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31810 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
31820 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
31830 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
31840 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31860 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
31870 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
31880 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
31890 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
318a0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
318b0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
318c0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
318d0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
318e0 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
318f0 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
31900 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
31910 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
31920 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
31930 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31940 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
31950 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
31960 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
31970 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
31980 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
31990 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
319a0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
319b0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
319c0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
319d0 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
319e0 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
319f0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
31a00 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
31a10 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
31a20 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
31a30 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
31a40 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
31a50 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
31a60 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
31a70 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
31a80 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
31a90 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
31aa0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
31ab0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
31ac0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
31ad0 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
31ae0 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
31af0 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
31b00 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
31b10 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
31b20 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
31b30 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
31b40 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
31b50 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
31b60 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
31b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
31b80 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
31b90 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
31ba0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
31bb0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
31bc0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
31bd0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
31be0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31bf0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
31c00 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
31c10 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
31c20 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
31c30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
31c40 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
31c50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
31c60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31c70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
31c80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31c90 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
31ca0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
31cb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
31cc0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
31cd0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
31ce0 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
31cf0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
31d00 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
31d10 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
31d20 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
31d30 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
31d40 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
31d50 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
31d60 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
31d70 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
31d80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
31d90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
31da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31db0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
31dc0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
31dd0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
31de0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31df0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
31e00 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
31e10 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
31e20 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
31e30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
31e40 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
31e50 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
31e60 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
31e70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
31e80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31e90 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
31ea0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
31eb0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
31ec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31ed0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31ee0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
31ef0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
31f00 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
31f10 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
31f20 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
31f30 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
31f40 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
31f50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31f60 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
31f70 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
31f80 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
31f90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
31fa0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31fb0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
31fc0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
31fd0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
31fe0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31ff0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32000 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
32010 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
32020 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
32030 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
32040 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
32050 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
32060 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
32070 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
32080 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
32090 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
320a0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
320b0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
320c0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
320d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
320e0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
320f0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
32100 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
32110 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
32120 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
32130 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
32140 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32150 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
32160 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
32170 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
32180 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
32190 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
321a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
321b0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
321c0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
321d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
321e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
321f0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
32200 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32210 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
32220 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
32230 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
32240 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
32250 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
32260 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
32270 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
32280 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
32290 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
322a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
322b0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
322c0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
322d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
322e0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
322f0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
32300 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
32310 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
32320 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
32330 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
32340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32350 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
32360 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
32370 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
32380 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
32390 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
323a0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
323b0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
323c0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
323d0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
323e0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
323f0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
32400 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
32410 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
32420 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
32430 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32440 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
32450 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
32460 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
32470 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
32480 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
32490 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
324a0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
324b0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
324c0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
324d0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
324e0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
324f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
32500 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
32510 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32520 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
32530 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
32540 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
32550 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
32560 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32570 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
32580 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
32590 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
325a0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
325b0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
325c0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
325d0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
325e0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
325f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32600 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
32610 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
32620 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
32630 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
32640 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
32650 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
32660 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
32670 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32680 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
32690 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
326a0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
326b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
326c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
326d0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
326e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
326f0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
32700 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
32710 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
32720 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
32730 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32740 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
32750 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
32760 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32770 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
32780 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
32790 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
327a0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
327b0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
327c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
327d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
327e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
327f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
32800 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
32810 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32820 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
32830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32840 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
32850 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
32860 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
32870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32880 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
32890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
328a0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
328b0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
328c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
328d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
328e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
328f0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
32900 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
32910 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
32920 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
32930 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
32940 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
32950 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
32960 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
32970 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
32980 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
32990 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
329a0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
329b0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
329c0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
329d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
329e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
329f0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
32a00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
32a10 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
32a20 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
32a30 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
32a40 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
32a50 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
32a60 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
32a70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
32a80 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
32a90 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
32aa0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
32ab0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
32ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32ad0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
32ae0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
32af0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
32b00 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
32b10 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
32b20 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
32b30 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
32b40 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
32b50 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
32b60 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
32b70 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
32b80 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
32b90 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
32ba0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
32bb0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
32bc0 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
32bd0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
32be0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
32bf0 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
32c00 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
32c10 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
32c20 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
32c30 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
32c40 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
32c50 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
32c60 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
32c70 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
32c80 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
32c90 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
32ca0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
32cb0 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
32cc0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
32cd0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
32ce0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
32cf0 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
32d00 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
32d10 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
32d20 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
32d30 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
32d40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
32d50 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
32d60 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
32d70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
32d80 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
32d90 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
32da0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
32db0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
32dc0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
32dd0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
32de0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
32df0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
32e00 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
32e10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
32e20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32e30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32e40 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
32e50 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
32e60 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
32e70 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
32e80 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
32e90 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
32ea0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
32eb0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
32ec0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
32ed0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
32ee0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
32ef0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
32f00 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
32f10 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
32f20 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
32f30 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
32f40 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
32f50 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
32f60 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
32f70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32f80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32f90 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32fa0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32fb0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
32fc0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
32fd0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
32fe0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
32ff0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
33000 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
33010 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
33020 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
33030 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33040 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
33050 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
33060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33070 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
33080 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
33090 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
330a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
330b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
330c0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
330d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
330e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
330f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
33100 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
33110 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
33120 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
33130 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
33140 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
33150 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
33160 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
33170 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
33180 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
33190 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
331a0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
331b0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
331c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
331d0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
331e0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
331f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33200 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33210 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
33220 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
33230 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33240 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33250 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
33260 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
33270 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
33280 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
33290 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
332a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
332b0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
332c0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
332d0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
332e0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
332f0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
33300 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
33310 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33320 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
33330 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
33340 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
33350 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
33360 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
33370 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
33380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33390 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
333a0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
333b0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
333c0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
333d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
333e0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
333f0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
33400 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33410 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
33420 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33430 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
33440 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33450 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
33460 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33470 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
33480 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33490 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
334a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
334b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
334c0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
334d0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
334e0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
334f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
33500 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
33510 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
33520 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33530 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
33540 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
33550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33560 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
33570 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
33580 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
33590 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
335a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
335b0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
335c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
335d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
335e0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
335f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33600 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33610 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
33620 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33630 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33640 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33650 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33660 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
33670 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33680 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33690 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
336a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
336b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
336c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
336d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
336e0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
336f0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
33700 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
33710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33730 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33740 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
33750 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33760 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
33770 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
33780 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
33790 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
337a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
337b0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
337c0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
337d0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
337e0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
337f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33800 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
33810 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
33820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
33830 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
33840 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
33850 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
33860 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33870 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
33880 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33890 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
338a0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
338b0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
338c0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
338d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
338e0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
338f0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
33900 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
33910 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
33920 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
33930 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
33940 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
33950 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
33960 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
33970 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
33980 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
33990 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
339a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
339b0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
339c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
339d0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
339e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
339f0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
33a00 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
33a10 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
33a20 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
33a30 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
33a40 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
33a50 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
33a60 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
33a70 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
33a80 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33a90 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
33aa0 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
33ab0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
33ac0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
33ad0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
33ae0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
33af0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
33b00 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
33b10 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
33b20 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
33b30 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
33b40 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
33b50 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
33b60 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
33b70 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
33b80 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
33b90 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
33ba0 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
33bb0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
33bc0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
33bd0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
33be0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
33bf0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
33c00 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33c10 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
33c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
33c30 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
33c40 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
33c50 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
33c60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
33c70 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
33c80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
33c90 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
33ca0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
33cb0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
33cc0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
33cd0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
33ce0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
33cf0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
33d00 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
33d10 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
33d20 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
33d30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
33d40 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
33d50 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
33d60 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
33d70 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
33d80 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
33d90 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
33da0 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
33db0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
33dc0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
33dd0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
33de0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
33df0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
33e00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33e10 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
33e20 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
33e30 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
33e40 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
33e50 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
33e60 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
33e70 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
33e80 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
33e90 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
33ea0 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
33eb0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
33ec0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
33ed0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
33ee0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
33ef0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
33f00 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
33f10 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
33f20 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
33f30 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
33f40 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
33f50 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
33f60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
33f70 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
33f80 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
33f90 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
33fa0 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
33fb0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
33fc0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
33fd0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
33fe0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
33ff0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
34000 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
34010 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
34020 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
34030 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
34040 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
34050 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
34060 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
34070 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
34080 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
34090 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
340a0 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
340b0 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
340c0 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
340d0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
340e0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
340f0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
34100 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
34110 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
34120 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
34130 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
34140 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
34150 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
34160 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
34170 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
34180 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
34190 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
341a0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
341b0 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
341c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
341d0 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
341e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
341f0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
34200 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34210 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34220 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34230 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
34240 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
34250 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
34260 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
34270 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
34280 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
34290 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
342a0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
342b0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
342c0 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
342d0 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
342e0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
342f0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
34300 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
34310 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
34320 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
34330 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
34340 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
34350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34360 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
34370 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
34380 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
34390 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
343a0 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
343b0 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
343c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
343d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
343e0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
343f0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
34400 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
34410 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34420 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
34430 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
34440 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
34450 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
34460 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
34470 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
34480 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34490 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
344a0 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
344b0 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
344c0 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
344d0 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
344e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
344f0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
34500 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
34510 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
34520 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
34530 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
34540 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
34550 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
34560 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
34570 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
34580 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
34590 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
345a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
345b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
345c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
345d0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
345e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
345f0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
34600 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
34610 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
34620 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
34630 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
34640 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
34650 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
34660 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
34670 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
34680 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34690 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
346a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
346b0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
346c0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
346d0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
346e0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
346f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
34700 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
34710 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
34720 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
34730 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34740 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
34750 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
34760 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
34770 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
34780 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
34790 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
347a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
347b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
347c0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
347d0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
347e0 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
347f0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
34800 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
34810 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
34820 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
34830 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
34840 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
34850 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
34860 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
34870 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
34880 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
34890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
348a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
348b0 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
348c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
348d0 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
348e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
348f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
34900 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34910 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34920 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
34930 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
34940 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
34950 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
34960 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
34970 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
34980 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
34990 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
349a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
349b0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
349c0 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
349d0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
349e0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
349f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
34a00 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
34a10 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
34a20 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
34a30 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
34a40 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
34a50 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
34a60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34a70 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
34a80 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
34a90 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
34aa0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
34ab0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
34ac0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
34ad0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
34ae0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
34af0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
34b00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
34b10 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
34b20 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
34b30 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
34b40 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
34b50 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
34b60 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
34b70 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
34b80 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
34b90 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
34ba0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
34bb0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
34bc0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
34bd0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
34be0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
34bf0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
34c00 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
34c10 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
34c20 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
34c30 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
34c40 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
34c50 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
34c60 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
34c70 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34c80 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
34c90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
34ca0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34cb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34cc0 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
34cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
34ce0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
34cf0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
34d00 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
34d10 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
34d20 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
34d30 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
34d40 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34d50 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
34d60 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
34d70 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
34d80 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
34d90 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
34da0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
34db0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
34dc0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
34dd0 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
34de0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
34df0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
34e00 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
34e10 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
34e20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
34e30 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
34e40 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
34e50 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
34e60 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
34e70 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
34e80 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
34e90 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
34ea0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
34eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
34ec0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
34ed0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
34ee0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
34ef0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
34f00 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
34f10 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
34f20 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
34f30 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
34f40 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
34f50 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
34f60 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
34f70 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
34f80 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
34f90 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
34fa0 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
34fb0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
34fc0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
34fd0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
34fe0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
34ff0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
35000 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
35010 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
35020 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
35030 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
35040 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
35050 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
35060 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
35070 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
35080 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
35090 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
350a0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
350b0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
350c0 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61  for a SEE databa
350d0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
350e0 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
350f0 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69  of the SEE routi
35100 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
35110 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
35120 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
35130 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
35140 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
35150 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
35160 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
35170 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
35180 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
35190 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
351a0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
351b0 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
351c0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
351d0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
351e0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
351f0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
35200 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
35210 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
35220 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
35230 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
35240 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
35250 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
35260 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
35270 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
35280 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
35290 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65  t Time.**.** The
352a0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
352b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
352c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
352d0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
352e0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
352f0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
35300 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
35310 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
35320 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
35330 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
35340 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
35350 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
35360 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
35370 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
35380 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
35390 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
353a0 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
353b0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
353c0 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
353d0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
353e0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
353f0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
35400 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
35410 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
35420 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
35430 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65  ** ^SQLite imple
35440 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
35450 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
35460 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
35470 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
35480 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
35490 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  fs] object.  If 
354a0 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
354b0 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65  hod.** of the de
354c0 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74  fault VFS is not
354d0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72   implemented cor
354e0 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69  rectly, or not i
354f0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a  mplemented at.**
35500 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62   all, then the b
35510 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
35520 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64  e3_sleep() may d
35530 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20  eviate from the 
35540 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69  description.** i
35550 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
35560 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e  aragraphs..*/.in
35570 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
35580 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
35590 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
355a0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
355b0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
355c0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
355d0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
355e0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
355f0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
35600 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
35610 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
35620 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
35630 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
35640 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
35650 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
35660 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
35670 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
35680 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
35690 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
356a0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
356b0 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
356c0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
356d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
356e0 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
356f0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
35700 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
35710 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
35720 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
35730 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
35740 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
35750 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35760 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
35770 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
35780 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
35790 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
357a0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
357b0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
357c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
357d0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
357e0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
357f0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
35800 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
35810 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
35820 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
35830 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
35840 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
35850 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
35860 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
35870 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
35880 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
35890 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
358a0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
358b0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
358c0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
358d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
358e0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
358f0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
35900 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
35910 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
35920 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
35930 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
35940 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
35950 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
35960 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
35970 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
35980 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
35990 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
359a0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
359b0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
359c0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
359d0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
359e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
359f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
35a00 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
35a10 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
35a20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
35a30 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
35a40 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
35a50 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
35a60 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
35a70 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
35a80 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
35a90 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
35aa0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
35ab0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
35ac0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
35ad0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
35ae0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
35af0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
35b00 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
35b10 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
35b20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
35b30 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
35b40 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
35b50 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
35b60 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
35b70 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
35b80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  lling [sqlite3_o
35b90 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  pen] or [sqlite3
35ba0 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65  _open_v2].  Othe
35bb0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
35bc0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
35bd0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
35be0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
35bf0 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65  es may fail.  He
35c00 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d  re is an.** exam
35c10 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f  ple of how to do
35c20 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20   this using C++ 
35c30 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73  with the Windows
35c40 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20   Runtime:.**.** 
35c50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
35c60 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61  >.** LPCWSTR zPa
35c70 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74  th = Windows::St
35c80 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69  orage::Applicati
35c90 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d  onData::Current-
35ca0 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  >.** &nbsp;     
35cb0 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d  TemporaryFolder-
35cc0 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a  >Path->Data();.*
35cd0 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26  * char zPathBuf&
35ce0 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31  #91;MAX_PATH + 1
35cf0 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74  &#93;;.** memset
35d00 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69  (zPathBuf, 0, si
35d10 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b  zeof(zPathBuf));
35d20 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75  .** WideCharToMu
35d30 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c  ltiByte(CP_UTF8,
35d40 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a   0, zPath, -1, z
35d50 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28  PathBuf, sizeof(
35d60 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e  zPathBuf),.** &n
35d70 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e  bsp;     NULL, N
35d80 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33  ULL);.** sqlite3
35d90 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20  _temp_directory 
35da0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
35db0 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66  f("%s", zPathBuf
35dc0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
35dd0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c  ockquote>.*/.SQL
35de0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
35df0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
35e00 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
35e10 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
35e20 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
35e30 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 69  ding Database Fi
35e40 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
35e50 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
35e60 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
35e70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
35e80 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
35e90 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
35ea0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
35eb0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64  ory), then all d
35ec0 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a  atabase files.**
35ed0 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68 20   specified with 
35ee0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  a relative pathn
35ef0 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64 20  ame and created 
35f00 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a  or accessed by.*
35f10 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  * SQLite when us
35f20 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77  ing a built-in w
35f30 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f  indows [sqlite3_
35f40 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20  vfs | VFS] will 
35f50 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f  be assumed.** to
35f60 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20   be relative to 
35f70 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
35f80 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61  ^ ^If this varia
35f90 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a  ble is a NULL.**
35fa0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
35fb0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
35fc0 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  at all database 
35fd0 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a  files specified.
35fe0 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 69  ** with a relati
35ff0 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20  ve pathname are 
36000 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20  relative to the 
36010 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
36020 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f  y.** for the pro
36030 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20  cess.  Only the 
36040 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65  windows VFS make
36050 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c  s use of this gl
36060 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  obal.** variable
36070 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20  ; it is ignored 
36080 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e  by the unix VFS.
36090 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20  .**.** Changing 
360a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69  the value of thi
360b0 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65  s variable while
360c0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
360d0 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65  ection is.** ope
360e0 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  n can result in 
360f0 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62 61  a corrupt databa
36100 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  se..**.** It is 
36110 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
36120 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
36130 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
36140 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
36150 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
36160 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
36170 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
36180 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
36190 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
361a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
361b0 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
361c0 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
361d0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
361e0 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
361f0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
36200 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
36210 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
36220 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
36230 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
36240 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
36250 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
36260 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
36270 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
36280 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
36290 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
362a0 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
362b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f  *.** ^The [data_
362c0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
362d0 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
362e0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
362f0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
36300 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
36310 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36320 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
36330 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
36340 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f  e,.** the [data_
36350 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
36360 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
36370 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
36380 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
36390 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
363a0 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
363b0 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
363c0 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
363d0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
363e0 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
363f0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
36400 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
36410 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
36420 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
36430 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
36440 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
36450 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
36460 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
36470 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
36480 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
36490 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
364a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
364b0 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
364c0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f  se of the [data_
364d0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
364e0 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
364f0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
36500 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
36510 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64   *sqlite3_data_d
36520 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
36530 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
36540 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
36550 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
36560 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
36570 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
36580 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
36590 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
365a0 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
365b0 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
365c0 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
365d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
365e0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
365f0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
36600 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
36610 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
36620 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
36630 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
36640 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
36650 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
36660 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
36670 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
36680 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
36690 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
366a0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
366b0 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
366c0 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
366d0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
366e0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
366f0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
36700 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
36710 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
36720 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
36730 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
36740 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
36750 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
36760 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
36770 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
36780 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
36790 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
367a0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
367b0 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
367c0 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
367d0 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
367e0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
367f0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
36800 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
36810 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
36820 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
36830 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
36840 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
36850 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
36860 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
36870 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
36880 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
36890 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
368a0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
368b0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
368c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
368d0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
368e0 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
368f0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
36900 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
36910 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
36920 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
36930 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
36940 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
36950 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
36960 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
36970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36980 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
36990 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
369a0 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
369b0 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61  s.  ^The [databa
369c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
369d0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
369e0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
369f0 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
36a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36a10 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68  ].** that was th
36a20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
36a30 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
36a40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
36a50 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
36a60 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
36a70 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
36a80 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
36a90 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
36aa0 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  lace..*/.sqlite3
36ab0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
36ac0 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
36ad0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36ae0 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20  REF: Return The 
36af0 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44  Filename For A D
36b00 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
36b10 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
36b20 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d  lite3_db_filenam
36b30 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(D,N) interface
36b40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36b50 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65  er to a filename
36b60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
36b70 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f  ith database N o
36b80 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  f connection D. 
36b90 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62   ^The main datab
36ba0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20  ase file.** has 
36bb0 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e  the name "main".
36bc0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
36bd0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
36be0 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61  se N on the data
36bf0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
36c00 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61  on D, or if data
36c10 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70  base N is a temp
36c20 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f  orary or in-memo
36c30 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  ry database, the
36c40 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n.** a NULL poin
36c50 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
36c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65  .**.** ^The file
36c70 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79  name returned by
36c80 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
36c90 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  s the output of 
36ca0 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68  the.** xFullPath
36cb0 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74  name method of t
36cc0 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f  he [VFS].  ^In o
36cd0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
36ce0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  filename.** will
36cf0 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   be an absolute 
36d00 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69  pathname, even i
36d10 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75  f the filename u
36d20 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74  sed.** to open t
36d30 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67  he database orig
36d40 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49  inally was a URI
36d50 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74   or relative pat
36d60 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  hname..*/.const 
36d70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62  char *sqlite3_db
36d80 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65  _filename(sqlite
36d90 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61  3 *db, const cha
36da0 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a  r *zDbName);../*
36db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
36dc0 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74  termine if a dat
36dd0 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e  abase is read-on
36de0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ly.**.** ^The sq
36df0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
36e00 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  y(D,N) interface
36e10 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68   returns 1 if th
36e20 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20  e database N.** 
36e30 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20  of connection D 
36e40 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20  is read-only, 0 
36e50 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72  if it is read/wr
36e60 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20  ite, or -1 if N 
36e70 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61  is not.** the na
36e80 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  me of a database
36e90 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   on connection D
36ea0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36eb0 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  _db_readonly(sql
36ec0 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
36ed0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
36ee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36ef0 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
36f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36f10 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
36f20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36f30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
36f40 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
36f50 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
36f60 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
36f70 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
36f80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36f90 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
36fa0 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
36fb0 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
36fc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
36fd0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
36fe0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
36ff0 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
37000 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
37010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37020 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
37030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37040 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
37050 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
37060 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
37070 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
37080 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
37090 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
370a0 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
370b0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
370c0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
370d0 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
370e0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
370f0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
37100 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
37110 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
37120 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
37130 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
37140 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
37150 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
37160 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
37170 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37180 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
37190 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
371a0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
371b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
371c0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
371d0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
371e0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
371f0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
37200 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
37210 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
37220 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
37230 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
37240 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
37250 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
37260 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
37270 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
37280 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
37290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
372a0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
372b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
372c0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
372d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
372e0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
372f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
37300 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37310 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
37320 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
37330 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
37340 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
37350 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
37360 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
37370 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
37380 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
37390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
373a0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
373b0 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
373c0 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
373d0 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
373e0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
373f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
37400 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
37410 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
37420 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
37430 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
37440 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
37450 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
37460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
37470 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
37480 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
37490 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
374a0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
374b0 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
374c0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
374d0 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
374e0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
374f0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
37500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37510 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
37520 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
37530 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
37540 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
37550 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61  .** The commit a
37560 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  nd rollback hook
37570 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e   callbacks are n
37580 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a  ot reentrant..**
37590 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
375a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
375b0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
375c0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
375d0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
375e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
375f0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
37600 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
37610 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
37620 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
37630 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
37640 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
37650 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
37660 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
37670 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
37680 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
37690 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
376a0 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
376b0 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
376c0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
376d0 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e   that running an
376e0 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74  y other SQL stat
376f0 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  ements, includin
37700 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
37710 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c  nts,.** or merel
37720 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
37730 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
37740 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
37750 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66  ep()] will modif
37760 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
37770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
37780 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
37790 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
377a0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
377b0 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
377c0 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
377d0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
377e0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
377f0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
37800 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
37810 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
37820 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
37830 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
37840 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
37850 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
37860 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
37870 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
37880 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
37890 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
378a0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
378b0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
378c0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
378d0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
378e0 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
378f0 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
37900 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
37910 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
37920 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
37930 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
37940 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
37950 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
37960 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
37970 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
37980 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
37990 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
379a0 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
379b0 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
379c0 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
379d0 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
379e0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
379f0 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
37a00 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
37a10 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
37a20 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
37a30 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
37a40 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
37a50 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
37a60 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
37a70 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
37a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37a90 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
37aa0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
37ab0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37ac0 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
37ad0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
37ae0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
37af0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
37b00 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
37b10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
37b20 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
37b30 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
37b40 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
37b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37b60 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
37b70 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
37b80 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
37b90 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
37ba0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
37bb0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
37bc0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
37bd0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
37be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
37bf0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
37c00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
37c10 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
37c20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
37c30 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
37c40 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
37c50 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
37c60 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37c70 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
37c80 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
37c90 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37ca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37cb0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
37cc0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
37cd0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
37ce0 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
37cf0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
37d00 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
37d10 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
37d20 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
37d30 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
37d40 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
37d50 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
37d60 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
37d70 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
37d80 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
37d90 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
37da0 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
37db0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
37dc0 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
37dd0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
37de0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
37df0 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
37e00 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
37e10 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
37e20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
37e30 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
37e40 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
37e50 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
37e60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
37e70 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
37e80 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
37e90 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
37ea0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
37eb0 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
37ec0 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
37ed0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
37ee0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
37ef0 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
37f00 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
37f10 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
37f20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
37f30 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
37f40 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
37f50 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
37f60 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
37f70 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
37f80 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
37f90 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
37fa0 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
37fb0 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
37fc0 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
37fd0 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
37fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
37ff0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
38000 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
38010 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
38020 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
38030 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
38040 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
38050 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
38060 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
38070 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
38080 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
38090 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
380a0 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
380b0 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
380c0 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
380d0 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
380e0 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
380f0 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
38100 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
38110 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
38120 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
38130 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
38140 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
38150 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
38160 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
38170 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
38180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
38190 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
381a0 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
381b0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
381c0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
381d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
381e0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
381f0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
38200 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
38210 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
38220 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
38230 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
38240 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
38250 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
38260 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
38270 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
38280 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
38290 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
382a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
382b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
382c0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
382d0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
382e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
382f0 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
38300 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
38310 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
38320 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
38330 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
38340 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
38350 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38360 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
38370 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
38380 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
38390 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
383a0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
383b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  )], [sqlite3_rol
383c0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 2c 0a 2a  lback_hook()],.*
383d0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  * and [sqlite3_p
383e0 72 65 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  reupdate_hook()]
383f0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a   interfaces..*/.
38400 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
38410 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
38420 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
38430 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
38440 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
38450 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
38460 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
38470 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38480 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
38490 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
384a0 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 5e  er Cache.**.** ^
384b0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
384c0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
384d0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
384e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
384f0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
38500 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
38510 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
38520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
38530 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
38540 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
38550 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
38560 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
38570 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
38580 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
38590 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
385a0 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
385b0 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
385c0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
385d0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
385e0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
385f0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
38600 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
38610 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
38620 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
38630 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
38640 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
38650 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
38660 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
38670 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
38680 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
38690 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
386a0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
386b0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
386c0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
386d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
386e0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
386f0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
38700 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
38710 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
38720 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38730 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
38740 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
38750 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
38760 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
38770 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
38780 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
38790 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
387a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
387b0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
387c0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
387d0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
387e0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
387f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
38800 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
38810 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
38820 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
38830 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by d